The Building Coder

Wrangling Revisions with Ruby

Here is a write-up by Andy Holmes, Integration Specialist at OPX design consultancy on a Ruby project that uses a lot of different Revit API features, e.g., revisions on sheet, DMU updaters, Idling and document events, and creating a Ruby 'add-in' by using an application-level macro that has no macros in it.

This write-up will soon be made available on the redesigned OPX website, and the code is already freely available on GitHub.

Andy adds that Mat is colleague who works with Revit and came up with the idea. Andy said it was doable (and did it). He also notes that got frustrated with the API a number of times and that might be noticeable in the tone. :-)

So here goes:

Revit API: Wrangling Revisions with Ruby

OPXer Mat Hart came up with an idea for managing Revit project sheets: he wanted to have a master schedule log that would keep track of all of the revisions for every sheet, like this:

The problem is that, as of Revit 2014, you can’t make Revisions be columns in a schedule – it’s just not something that Revit can do. In the picture above, the Revisions columns aren’t really Revisions, they are actually Fields added to a sheet list Schedule from Parameters that were given the exact same names as Revisions.

What Mat wanted was for the sheet list Schedule (henceforth being referred to as the 'Sheet Log') to automatically stay in sync with the columns that are named after Revisions:

1. If you added a new Revision to the project, the Sheet Log would automatically get a new column added with the name of the Revision.
2. Checking or unchecking a Revision column for a sheet would automatically update that sheet’s Revisions on Sheet parameter AND Title Block Revision schedule, as shown here:


3. Adding/deleting Revision Cloud to a sheet or checking/unchecking values in a sheet’s Revisions on Sheet parameter would automatically update the Sheet Log.

So, in other words, the goal for this effort was to allow the Sheet Log to be a single master list of all sheets showing which sheets are part of each Revision. Automating all of this would avoid the human errors that come from having to manually keep track of the relationships between sheet revisions and a master sheet log.

Revit 2014 API: A Must-Have for Revisions and Ruby

It turns out that this project would not have been possible prior to Revit 2014, since only in 2014 did Autodesk add to the Revit API the ability to access and manipulate Revisions on Sheet. Fortunately, they did add Revisions on Sheet to the 2014 API, so we were in luck.

Also, the 2014 API (via the SharpDevelop API development tool provided with Revit) added the ability to develop Revit macros in Ruby (rather than C# or Python), so Ruby was used to develop the functionality. (IronRuby, the Microsoft .NET specific Ruby version needed for Revit API development, is actually no longer under development by Microsoft, but it works for Revit development).

opxRevisionAndSheetLogUpdater

The resulting project, opxRevisionAndSheetLogUpdater, is a set of Ruby files that can be used by copying them into the Revit 2014 macros directory. That very long directory is something like:

C:\ProgramData\Autodesk\Revit\Macros\2014\Revit\AppHookup\opxRevisionAndSheetLogUpdater\Source\opxRevisionAndSheetLogUpdater

This is where new macros are created when using the Macro Manager.

The Ruby code for this project is available from the opxRevisionAndSheetLogUpdater GitHub repository. You can download the code and explore it. You can also email questions about the project to aholmes@opxglobal.com.

Hurdles

Some key hurdles that were cleared in creating this project:

• Creating Ruby code that could easily run in Revit – I used RevitRubyShell and tested all my code in it before I ever turned it into a macro. I develop in Sublime Text and load the files into RevitRubyShell for testing. It’s fast and easy.
• Determining the IronRuby syntax for accessing Revit .NET classes and interfaces – It took some time to find the proper ways to interact with .NET from Ruby. There were a number of these that would be easier if you’re familiar with .NET CLRs and DLRs. I did go into the IronRuby source code on GitHub at one or two points. For example, using the IUpdater interface and adding a Ruby method as a Revit DocumentChanged event handler uses this syntax:

  # IUpdater-based class definition.
  
  class SheetRevisionChangeUpdater
    include Autodesk::Revit::DB::IUpdater
    ...
  end
  
  # Create and register an updater.
  
  updater = SheetRevisionChangeUpdater.new(
    app.ActiveAddInId )
  
  UpdaterRegistry.RegisterUpdater( updater )
  
  ...
  
  app.DocumentChanged.Add( updater.method(
    :on_doc_changed_new_revision_handler) )
  

• Working around Revit and Revit API limitations and edge cases – You often don’t know exactly how the Revit API will behave until you test it, particularly when working with DMU Updaters and events like DocumentCreated and DocumentChanged. You have to try something to see whether it works, and the opxRevisionAndSheetLogUpdater code has some code and comment sections that elaborate on these. One example: the revision title block doesn't update correctly when the API removes the last Revision on Sheet. That just seems like a bug, really. The workaround was to re-add and re-remove the revision in separate DB transactions.

  Also, the Revit API simply doesn’t allow you to do certain things. You tend to find these limitations only when you reach the point of needing to code certain functionality. You can’t set conditional formatting of fields, or create non-shared parameters, or manipulate revision clouds, as examples.

• Turning Ruby code into a Revit macro that loads on start-up – You can’t create a Revit add-in in Ruby, because there is no IronRuby compiler, and add-ins have to be .NET assemblies (i.e., DLLs). So, rather than translate the entire project into C# to make an add-in, the code remains as a macro. The trick is that there is no macro – the code is a Ruby Revit macro module that contains zero macros, but loads on start-up. That way, the user can’t forget to run a macro, or disable macros, or other things that would prevent the code from running.

Invaluable Assistance

These sources were hugely useful in developing this code:

• The Building Coder – Jeremy Tammik’s enormously valuable blog that examines the Revit API.
• Boost Your BIM – Harry Mattison’s outstanding Revit API blog. Harry also created the Revit 2014 Macros in Ruby YouTube video.
• Revit 2014 Macros in Ruby – The how-to for using the Revit Macro Manager and SharpDevelop to create a Ruby Revit macro. This shows how the ThisApplication.rb is created and how to switch back and forth between SharpDevelop and Revit to test a Ruby macro.
• Spiderinnet – Another source of Revit API knowledge.

Installation Addendum

A quick Revit Ruby addendum on Installing Revit 2014 API add-ins.

I’m adding this since I just spent a while on this potential hiccup for Revit Ruby users. See the linked document for details (step 5 of the RevitRubyShell install steps). The short version is that installing a recent version of standalone IronPython breaks IronRuby, so Revit Ruby macros and the RevitRubyShell won’t work.

I’m probably the only person who installed IronPython and then started using the Revit Ruby API, but it was so painful to figure out I decided to share it anyway, just in case ... :-)

Also, thanks for RevitLookup! I use it constantly.

Daylighting Extension and Splitting with Taps

Here is a quick update on the status of the daylighting analysis technology preview and some helpful advice for anyone trying to split a duct or pipe with taps.

Daylighting Analysis

The Daylighting Analysis for Revit technology preview free analysis period has been extended until March 31 or until a commercial version becomes available, whichever comes first.

Find out more and download the updated plug-in from the Daylighting Analysis for Revit Autodesk Labs page.

Splitting a Duct or Pipe with Taps

Question: I would like to split a Duct or a Pipe in a way that retains the intact Revit functionality.

The user interface provides a command to split walls via Modify > Split Element > Split with Gap.

How can I programmatically achieve something similar to split a duct or a pipe?

Answer: The Duct and Pipe classes do not provide any built-in split functionality.

Here are a discussion on splitting a duct or pipe from 2012 and an older one from 2009.

Response: Splitting a pipe by shortening it and then creating a new one for the other end works fine for simple cases.

However, what can I do if there are taps connected to it?

In that case, shortening the pipe will remove the connection between the tap and the pipe and cause errors.

Creating a new pipe at the old one's location will not automatically reattach the tap.

So how can I split a pipe or a duct that has taps attached to it?

Answer: As always, the Revit API will not provide any additional functionality beyond what you have in the user interface.

From the UI standpoint, one would need to:

1. Remove the taps. In some cases, when you shorten a duct, Revit will throw an error saying that you need to delete the tap. In other cases it will not. Regardless, you need to get rid of them to create new ones. So, of course, you'll want to remember their type, location, orientation, etc.
2. Reconnect the branch to the newly created duct that supplements the old shortened one. In the UI, the 'extend' command will insert a tap for you. The API will as well, as we saw in some of the various cases during the development of the simpler rolling offset.

Response: I accept that the API will not provide any additional functionality beyond what you have in the user interface.

However, besides the 'Split with Gap' functionality for walls, the UI also provides a 'Split Element' command that does work for Ducts and Pipes. Are you saying this functionality is available programmatically? If so, where can I find it, please?

Secondly, you suggest to remove the taps and then recreate them.

In the UI, the extend method will only create the tap again if it is also defined in the DuctType and if the Preferred Junction Type is set to Tap. Furthermore, another thing that needs to be taken into account is that certain parameters might be set for the duct or pipe. and all of these parameter values will need to be copied to the newly created segment as well.

The function 'Split Elements' provided by the user interface does all of this automatically: it will just split the Duct and add a union family in between. That is exactly what I would like to achieve programmatically as well.

Answer: Thank you for the clarification and sorry for the detour.

I am sorry to say that you are right in not finding that access, and this functionality is currently not available through the API, so I submitted a wish list item on your behalf for it.

Deleting Unnamed Non-Hosting Reference Planes

Once upon a time, while teaching a Revit API class, the training participants identified a problem that was simple enough to be used as a filtered element collector learning example and did something useful at the same time: deleting reference planes not hosting any elements, implemented as the stand-alone external command DeleteUnnamedNonHostingReferencePlanes.

It deletes all reference planes that have not been named and are not hosting any elements.

Here is another thread discussing filtering reference planes and explaining the use of this.

The first part of the check, for a valid element name, is achieved by using a filtered element collector with an ElementParameterFilter that returns only those elements whose built-in parameter DATUM_TEXT that returns the reference plane element name has an empty string value.

The second part of the check, whether the reference plane is currently hosting any elements, is automatically executed by the Delete method itself, which fails if that is the case.

A developer now raised an issue with that command:

Question: I have been using the code to delete all unnamed reference planes that do not host any elements.

It worked fine for a long time, but now it is throwing an error and shutting down Revit.

Will you please check this.

Answer: Thank you for your query.

Basically, the short answer to this question is: no.

The utility command that you refer to was provided on The Building Coder as a learning example to show you how to solve a specific problem yourself.

It is completely unsupported, and any use you make of it is completely at your own risk.

We are more than happy to provide you with developer support for your own applications, but we cannot maintain sample code, nor can we provide any guarantees that the examples presented on the blog will work or be of any productive use at all, except for learning purposes.

Please rephrase the question to request support for solving a specific API related issue that you are encountering in your own application development, and we will be more than happy to help.

I hope you understand the difference.

So, alas, no help for that specific query.

On the other hand, I do wonder for myself what might have changed, and decided to explore the issue anyway.

Meaning that, as an exception, I can change that 'no' to a 'yes' for the nonce. Lucky you.

To do so, I implemented a new external command named CmdDeleteUnusedRefPlanes in The Building Coder samples, migrated the code to the current version and ran a quick test.

Unfortunately, it ended up being not so quick after all, as usual.

The original command uses a filtered element collector to retrieve all unnamed reference planes like this:

  // Construct a parameter filter to get only 
  // unnamed reference planes, i.e. reference 
  // planes whose name equals the empty string:
 
  BuiltInParameter bip
    = BuiltInParameter.DATUM_TEXT;
 
  ParameterValueProvider provider
    = new ParameterValueProvider(
      new ElementId( bip ) );
 
  FilterStringRuleEvaluator evaluator
    = new FilterStringEquals();
 
  FilterStringRule rule = new FilterStringRule(
    provider, evaluator, "", false );
 
  ElementParameterFilter filter
    = new ElementParameterFilter( rule );
 
  FilteredElementCollector col
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ReferencePlane ) )
      .WherePasses( filter );
 
  int n = 0;
  int nDeleted = 0;
 
  // No need to cast ... this is pretty nifty,
  // I find ... grab the elements as ReferencePlane
  // instances, since the filter guarantees that 
  // only ReferencePlane instances are selected.
 
  foreach( ReferencePlane rp in col )
  {
    ++n;
    nDeleted += DeleteIfNotHosting( rp ) ? 1 : 0;
  }

That part still works fine and remains unchanged.

As you can see, the original command loops through the resulting reference planes and calls the method DeleteIfNotHosting that performs the deletion using the doc.Delete method like this:

  /// <summary>
  /// Delete the given reference plane 
  /// if it is not hosting anything.
  /// </summary>
  /// <returns>True if the given reference plane
  /// was in fact deleted, else false.</returns>
  bool DeleteIfNotHosting( ReferencePlane rp )
  {
    bool rc = false;
 
    Document doc = rp.Document;
 
    Transaction tx = new Transaction( doc );
 
    tx.Start( "Delete ReferencePlane "
      + ( ++_i ).ToString() );
 
    // Deletion simply fails if the reference plane 
    // hosts anything. If so, the return value ids 
    // is null:
 
    ICollection<ElementId> ids = doc.Delete( rp );
 
    if( null == ids || 1 < ids.Count )
    {
      tx.RollBack();
    }
    else
    {
      tx.Commit();
      rc = true;
    }
    return rc;
  }

The Delete method overload taking an Element argument is deprecated in Revit 2014, so I replaced it by a call to the overload taking an element id instead:

    ICollection<ElementId> ids = doc.Delete( rp.Id );

When running the resulting command, the following exception is thrown:

Autodesk.Revit.Exceptions.ArgumentException:
  HResult=-2146233088
  Message=ElementId cannot be deleted.
Parameter name: elementId
  Source=RevitAPI
  ParamName=elementId
Stack Trace:
  at Autodesk.Revit.DB.Document.Delete(ElementId)
  at DeleteIfNotHosting(ReferencePlane rp)
  at CmdDeleteUnusedRefPlanes.Execute(...) ...

The comment in the original code states that "Deletion simply fails if the reference plane hosts anything. If so, the return value ids collection is null".

This behaviour has been modified in Revit 2014 to throw the exception listed above instead of simply failing.

In other words, this exception is thrown if the reference plane is in fact hosting any elements and therefore should not be removed.

Furthermore, the original command was implemented before I started pointing out that all transactions should best be encapsulated within a 'using' statement block.

Such a block and an exception handler should be added to the call.

Another check that was added in Revit 2014 prevents element deletion while iterating over a collection.

Attempting to delete an element as shown above within the loop iterating over the filtered element collector throws the following exception:

Autodesk.Revit.Exceptions.InvalidOperationException:
  HResult=-2146233088
  Message=The iterator cannot proceed due to changes made
  to the Element table in Revit's database (typically,
  This can be the result of an Element deletion).
  Source=RevitAPI
Stack Trace:
  at Autodesk.Revit.DB.FilteredElementIterator.MoveNext()
  at BuildingCoder.CmdDeleteUnusedRefPlanes.Execute() ...

One solution to all this is the following simplification.

Instead of using a separate transaction for each individual attempt to delete a reference plane, do them all in one single go.

Furthermore, extract the element ids from the filtered element collector and process them one by one in a separate follow-up loop.

Finally, add an exception handler around each call to the Delete method, since each call to it with a plane hosting elements will cause it to throw an exception.

Here is the complete resulting external command mainline Execute method implementation:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
  Document doc = uidoc.Document;
 
  // Construct a parameter filter to get only 
  // unnamed reference planes, i.e. reference 
  // planes whose name equals the empty string:
 
  BuiltInParameter bip
    = BuiltInParameter.DATUM_TEXT;
 
  ParameterValueProvider provider
    = new ParameterValueProvider(
      new ElementId( bip ) );
 
  FilterStringRuleEvaluator evaluator
    = new FilterStringEquals();
 
  FilterStringRule rule = new FilterStringRule(
    provider, evaluator, "", false );
 
  ElementParameterFilter filter
    = new ElementParameterFilter( rule );
 
  FilteredElementCollector col
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ReferencePlane ) )
      .WherePasses( filter );
 
  int n = 0;
  int nDeleted = 0;
 
  ICollection<ElementId> ids = col.ToElementIds();
 
  n = ids.Count();
 
  if( 0 < n )
  {
    using( Transaction tx = new Transaction( doc ) )
    {
      tx.Start( string.Format(
        "Delete {0} ReferencePlane{1}",
        n, Util.PluralSuffix( n ) ) );
 
      List<ElementId> ids2 = new List<ElementId>(
        ids );
 
      foreach( ElementId id in ids2 )
      {
        try
        {
          ICollection<ElementId> ids3 = doc.Delete(
            id );
 
          nDeleted += ids3.Count;
        }
        catch( Autodesk.Revit.Exceptions.ArgumentException )
        {
        }
      }
 
      tx.Commit();
    }
  }
 
  Util.InfoMsg( string.Format(
    "{0} unnamed reference plane{1} examined, "
    + "{2} element{3} in total were deleted.",
    n, Util.PluralSuffix( n ),
    nDeleted, Util.PluralSuffix( nDeleted ) ) );
 
  return Result.Succeeded;

Running this in the rac_basic_sample_project.rvt model produces the following result:

The new command CmdDeleteUnusedRefPlanes is included in The Building Coder samples, and the version discussed above is release 2014.0.107.0.

Starting to Clean Up For the Break

I am starting to clear up some open issues before the break. Here are a few that I can handle right here and now:

• Autodesk University classes ready for viewing and download
• Building Performance Analysis update
• Daylighting Analysis Tool for Revit update

I will obviously not be able to magically transform the entire backlog of interesting topics I still wish to share and discuss.

Still, I am continuously learning to be active and still take things easy, do what I do, not think too much, just act.

Here is a nice little anecdote to illustrate the principle:

A new Zen monk has just been admitted to the monastery.

He pays his respects to the master and says: "I'm new to the monastery, please show me the way."

The master asks, "Have you had breakfast?"

The novice replies, "Yes, just a moment ago."

"Then go and wash your eating bowl."

By the way, I wondered whether to use commas or colons in the lines above, and found a conclusive answer in the Grammar Monster discussion of quotation marks for quotes: "use commas for quotations that comprise fewer than 7 words and use colons for longer quotations". I did not know that before. Thank you, Grammar Monster.

Autodesk University Classes Ready for Viewing and Download

The AU class materials and recordings are now available for viewing and download from au.autodesk.com.

The search tool returns this year's classes as well as previous ones from 2011 and 2012.

Here are the results of searching for my classes:

• 2011 – CP4451 : Extensible Storage in the Revit 2012 API
• 2011 – CP6760-L : Revit 2012 API Extensible Storage Lab
• 2011 – CP4453 : Everything in Place with Revit MEP Programming
• 2012 – CP4107 : Let's Face It: New Revit 2013 User Interface API Functionality
• 2012 – CP4108 : Revit MEP Programming: All Systems Go
• 2012 – CP4109 : Revit API Roundtable: Meet the Champions
• 2013 – DV2010 : Advanced Revit 2014 API Features and Samples
• 2013 – DV1736 : Cloud-Based, Real-Time, Round-Trip, 2D Revit Model Editing on Any Mobile Device
• 2013 – DV1914 : Revit API Expert Roundtable: Open House on the Factory Floor

By the way, talking about AU, and what with the festive season and all, here is a picture of me at AU with a pretty big and festive bird:

Building Performance Analysis Update

I mentioned the Building Performance Analysis blog at autodesk.typepad.com/bpa last year.

The BPA team have completed a number of exciting projects since then.

Thanks to them, Revit 2014 now offers an entirely new way to create an Energy Analysis Model or EAM automatically from Revit building elements, as explained in their following discussions:

• Revit 2014 release news
• Energy analysis using Revit building elements
• Revit 2014 update release 1

If you are already working with the Revit Energy Analysis model or are interested in determination of realistic volumes of rooms and spaces for any purpose whatsoever, this is a topic you absolutely must dive into.

For starters, read the detailed explanation From BIM to BPA: What is an Energy Analysis Model (EAM)?

Expect more in this area!

Daylighting Analysis Tool for Revit Update

One of the BPA tools is the recently announced Daylighting Analysis Tool for Revit, which was just now updated and released for global distribution.

The Revit 2014 Daylighting Analysis plug-in uses the Autodesk 360 Rendering cloud service to perform very fast and physically accurate daylighting analyses from within Revit. In the current first release of the plug-in, it provides LEED IEQc8.1 2009 results for most models in less than 15 minutes.

Here is the detailed BPA presentation of daylighting as a service.

The features provided by the new update include:

• New localized EULA and installer allow global distribution.
• If no Rooms are defined in the model when Run Analysis is selected, the user is given a warning, but analysis will continue.
• A unit option has been added to the AVF results view so lux or foot-candles can be selected.
• The LEED Room parameters now show up as editable in the Room Properties panel when a Room is selected.
• The AVF legend has been improved by clipping the values shown in the AVF to 6000 lux to make the scale visible in the lower ranges. The full raw values are still stored in the Revit Extensible Storage for export.
• User can hide and unhide AVF grids by level to make viewing and navigation easier in 3d section cuts.
• If the user has modified the "LEED 2009…" 3d view, the view is reset to defaults for the analysis run. Best practice is for user to make a copy of that view to create a custom view style.
• The plug-in can now handle multiple projects and multiple concurrent analyses in Revit. It is still required to keep a project open until the analysis is complete and data is downloaded from the cloud service.
• The user will now receive a message if a job fails for any reason, and the successful results will be downloaded.

You can download the technology preview from Autodesk Labs: Download Daylighting Analysis Tool for Revit.

Driving CNC Fabrication and Shared Parameters

The topic of CNC fabrication of Revit BIM elements is continuing to grow in popularity.

As you already know, I published the ExportWallboard add-in to automatically isolate and export wall parts individually to DXF for CNC fabrication, then enhanced, renamed and published it on GitHub as ExportCncFab for William Spier's Autodesk University class on Design to Fabrication.

Those discussions were explicitly related to CNC fabrication up front. Numerous other topics here are also useful in that context.

I was unable to highlight and discuss the newly added CNC add-in enhancements in detail before AU, so let's make up for that now, as well as look at some funny examples of genius problem simplifications.

ExportCncFab Functionality

ExportCncFab now sports the following features:

• Exporting wall parts individually to DXF:
• Exporting individual compound wall parts
• Handling and dismissing a warning message
• Adding support for both pre- and post- part selection
• Handling temporary transactions and regeneration
• Support for export to SAT as well as DXF
• CNC fabrication export history tracking and creation of shared parameters
• A beautiful little external application to define a nice user interface

I already presented the details of the DXF export, so now let's take a look at the other three items.

By the way, for the sake of completeness, let me also mention this previous example of exporting walls and floors to SAT, before the advent of parts, and this implementation of saving a solid to a SAT file.

Adding Export to SAT Functionality

Since I want to present the wall parts export to DXF or SAT functionality as two separate options in the user interface, they each need to be implemented as separate external commands.

On the other hand, I obviously avoid duplicating the code, which is mostly identical.

One way to achieve that is implement the common DXF and SAT export functionality in a separate method CmdDxf.Execute2 that can be called from both commands and takes an argument to toggle between the DXF and SAT export.

With that in place, I can implement the new SAT export external command like this:

  [Transaction( TransactionMode.Manual )]
  public class CmdSat : IExternalCommand
  {
    public Result Execute(
      ExternalCommandData commandData,
      ref string message,
      ElementSet elements )
    {
      return CmdDxf.Execute2( commandData, true );
    }
  }

The DXF export command is almost identical, except for providing a 'false' argument to Execute2.

Both commands are forced to use manual transaction mode instead of read-only for two reasons: (i) they perform temporary modifications in the database to isolate the parts to export one by one, and (ii) they save the export history in shared parameters, requiring database update for storage.

Besides the pure export and history recording functionality, the Execute2 implementation is complicated further still, since it also handles a warning dialogue displayed by Revit to ask whether to "really print or export temp view modes". It does so by temporarily subscribing to the DialogBoxShowing event and providing the following OnDialogBoxShowing event handler for it:

  static void OnDialogBoxShowing(
    object sender,
    DialogBoxShowingEventArgs e )
  {
    TaskDialogShowingEventArgs e2
      = e as TaskDialogShowingEventArgs;
 
    if( null != e2 && e2.DialogId.Equals(
      "TaskDialog_Really_Print_Or_Export_Temp_View_Modes" ) )
    {
      int cmdLink
        = (int) TaskDialogResult.CommandLink2;
 
      e.OverrideResult( cmdLink );
    }
  }

Besides suppressing and handling that message, the Execute2 method also has to jump through a hoop or two to store the export history in the shared parameters, and check that they exist before doing so.

All together, it performs the following steps:

• Check we are in a valid document.
• Check we are in a valid 3D view.
• Check that parts visibility is turned on.
• Determine the elements to export, either via pre- or post-selection.
• Check that the export history shared parameters have been defined.
• Prompt to select the export target directory.
• Encapsulate the following actions in a transaction group that is ultimately rolled back, leaving the document unmodified by the part export.
• Within the transaction group, iterate over the selected parts one by one.
• For each part:
• Disable the view temporary isolate mode if it was previously active.
• Temporarily isolate the current element.
• Export the current view displaying only one element to DXF or SAT, respectively.
• Cache the export history for the current element.
• Roll back the transaction group.
• Store the export history in the shared parameters in a separate transaction that is obviously not rolled back and therefore needs to reside outside the previous transaction group.

This slightly convoluted process evolved step by step as the needs expanded. Surprisingly, it works completely reliably.

Here is the code implementing this in all its glory, including some interesting comments referring to the process itself and the migration from Revit 2013 to 2014:

  public static Result Execute2(
    ExternalCommandData commandData,
    bool exportToSatFormat )
  {
    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;
    }
 
    View view = doc.ActiveView;
 
    if( null == view || !( view is View3D ) )
    {
      ErrorMsg( "Please run this command in a valid"
        + " 3D view." );
      return Result.Failed;
    }
 
    if( PartsVisibility.ShowPartsOnly
      != view.PartsVisibility )
    {
      ErrorMsg( "Please run this command in a view"
        + " displaying parts and not source elements." );
      return Result.Failed;
    }
 
    // Define the list of views to export, 
    // including only the current 3D view
 
    List<ElementId> viewIds = new List<ElementId>( 1 );
 
    viewIds.Add( view.Id );
 
    // Iterate over all pre-selected parts
 
    List<ElementId> ids = null;
 
    Selection sel = uidoc.Selection;
 
    if( 0 < sel.Elements.Size )
    {
      foreach( Element e in sel.Elements )
      {
        if( !( e is Part ) )
        {
          ErrorMsg( "Please pre-select only gyp wallboard"
            + " parts before running this command." );
          return Result.Failed;
        }
 
        Part part = e as Part;
 
        ICollection<LinkElementId> lids
          = part.GetSourceElementIds();
 
        if( 1 != lids.Count )
        {
          ErrorMsg( "Gyp wallboard part has multiple"
            + " source elements." );
          return Result.Failed;
        }
 
        LinkElementId lid = lids.First<LinkElementId>();
        ElementId hostId = lid.HostElementId;
        ElementId linkedId = lid.LinkedElementId;
        ElementId parentId = hostId;
        ElementId partId = e.Id;
 
        // Determine parent category
 
        Element parent = doc.GetElement( parentId );
        Category cat = parent.Category;
 
        ICollection<ElementId> cids
          = part.GetSourceElementOriginalCategoryIds();
 
        if( 1 != cids.Count )
        {
          ErrorMsg( "Gyp wallboard part has multiple"
            + " source element categories." );
          return Result.Failed;
        }
 
        ElementId cid = cids.First<ElementId>();
 
        //cat = doc.GetElement( id ) as Category;
 
        // Expected parent category is OST_Walls
 
        BuiltInCategory bic
          = (BuiltInCategory) cid.IntegerValue;
 
        if( BuiltInCategory.OST_Walls != bic )
        {
          ErrorMsg( "Please pre-select only "
            + " gyp wallboard parts." );
 
          return Result.Failed;
        }
 
        if( null == ids )
        {
          ids = new List<ElementId>( 1 );
        }
 
        ids.Add( partId );
      }
 
      if( null == ids )
      {
        ErrorMsg( "Please pre-select only gyp wallboard"
          + " parts before running this command." );
        return Result.Failed;
      }
    }
 
    // If no parts were pre-selected, 
    // prompt for post-selection
 
    if( null == ids )
    {
      IList<Reference> refs = null;
 
      try
      {
        refs = sel.PickObjects( ObjectType.Element,
          new WallPartSelectionFilter(),
          "Please select wall parts." );
      }
      catch( Autodesk.Revit.Exceptions
        .OperationCanceledException )
      {
        return Result.Cancelled;
      }
      ids = new List<ElementId>(
        refs.Select<Reference, ElementId>(
          r => r.ElementId ) );
    }
 
    if( 0 == ids.Count )
    {
      ErrorMsg( "No valid parts selected." );
 
      return Result.Failed;
    }
 
    // Check for shared parameters 
    // to record export history
 
    ExportParameters exportParameters
      = new ExportParameters(
        doc.GetElement( ids[0] ) );
 
    if( !exportParameters.IsValid )
    {
      ErrorMsg( "Please initialise the CNC fabrication "
        + "export history shared parameters before "
        + "launching this command." );
 
      return Result.Failed;
    }
 
    if( !Util.BrowseDirectory( ref _folder, true ) )
    {
      return Result.Cancelled;
    }
 
    try
    {
      // Register event handler for 
      // "TaskDialog_Really_Print_Or_Export_Temp_View_Modes" 
      // dialogue
 
      uiapp.DialogBoxShowing
        += new EventHandler<DialogBoxShowingEventArgs>(
          OnDialogBoxShowing );
 
      object opt = exportToSatFormat
        ? (object) new SATExportOptions()
        : (object) new DXFExportOptions();
 
      //opt.FileVersion = ACADVersion.R2000;
 
      string filename;
 
      using( TransactionGroup txg = new TransactionGroup( doc ) )
      {
        txg.Start( "Export Wall Parts" );
 
        foreach( ElementId id in ids )
        {
          Element e = doc.GetElement( id );
 
          Debug.Assert( e is Part,
            "expected parts only" );
 
          Part part = e as Part;
 
          ICollection<LinkElementId> lids
            = part.GetSourceElementIds();
 
          Debug.Assert( 1 == lids.Count,
            "unexpected multiple part source elements." );
 
          LinkElementId lid = lids.First<LinkElementId>();
          ElementId hostId = lid.HostElementId;
          ElementId linkedId = lid.LinkedElementId;
          ElementId parentId = hostId;
          ElementId partId = e.Id;
 
          filename = string.Format( "{0}_{1}",
            parentId, partId );
 
          Element host = doc.GetElement( hostId );
 
          Debug.Assert( null != host, "expected to be able to access host element" );
          //Debug.Assert( ( host is Wall ), "expected host element to be a wall" ); 
          Debug.Assert( ( host is Wall ) || ( host is Part ), "expected host element to be a wall or part" );
          Debug.Assert( null != host.Category, "expected host element to have a valid category" );
          //Debug.Assert( host.Category.Id.IntegerValue.Equals( (int) BuiltInCategory.OST_Walls ), "expected host element to have wall category" );
          Debug.Assert( host.Category.Id.IntegerValue.Equals( (int) BuiltInCategory.OST_Walls ) || host.Category.Id.IntegerValue.Equals( (int) BuiltInCategory.OST_Parts ), "expected host element to have wall or part category" );
          Debug.Assert( ElementId.InvalidElementId != host.LevelId, "expected host element to have a valid level id" );
 
          if( ElementId.InvalidElementId != host.LevelId )
          {
            Element level = doc.GetElement( host.LevelId );
 
            filename = level.Name.Replace( ' ', '_' )
              + "_" + filename;
          }
 
          if( view.IsTemporaryHideIsolateActive() )
          {
            using( Transaction tx = new Transaction( doc ) )
            {
              tx.Start( "Disable Temporary Isolate" );
 
              view.DisableTemporaryViewMode(
                TemporaryViewMode.TemporaryHideIsolate );
 
              tx.Commit();
            }
 
            Debug.Assert( !view.IsTemporaryHideIsolateActive(),
              "expected to turn off temporary hide/isolate" );
          }
 
          using( Transaction tx = new Transaction( doc ) )
          {
            tx.Start( "Export Wall Part "
              + partId.ToString() );
 
            // This call requires a transaction.
 
            view.IsolateElementTemporary( partId );
 
            //List<ElementId> unhideIds = new List<ElementId>( 1 );
            //unhideIds.Add( partId );
            //view.UnhideElements( unhideIds );
 
            //doc.Regenerate(); // this is insufficient
 
            tx.Commit();
          }
 
          if( exportToSatFormat )
          {
            //ViewSet viewSet = new ViewSet();
            //
            //foreach( ElementId vid in viewIds )
            //{
            //  viewSet.Insert( doc.GetElement( vid ) 
            //    as View );
            //}
            //
            //doc.Export( _folder, filename, viewSet, 
            //  (SATExportOptions) opt ); // 2013
 
            doc.Export( _folder, filename, viewIds,
              (SATExportOptions) opt ); // 2014
          }
          else
          {
            doc.Export( _folder, filename, viewIds,
              (DXFExportOptions) opt );
          }
 
          // Update CNC fabrication 
          // export shared parameters -- oops, 
          // cannot do this immediately, since 
          // this transaction group will be
          // rolled back ... just save the 
          // element id and do it later
          // searately.
 
          //exportParameters.UpdateExportHistory( e );
          exportParameters.Add( e.Id );
        }
 
        // We do not commit the transaction group, 
        // because no modifications should be saved.
        // The transaction group is only created and 
        // started to encapsulate the transactions 
        // required by the IsolateElementTemporary 
        // method. Since the transaction group is not 
        // committed, the changes are automatically 
        // discarded.
 
        //txg.Commit();
      }
    }
    finally
    {
      uiapp.DialogBoxShowing
        -= new EventHandler<DialogBoxShowingEventArgs>(
          OnDialogBoxShowing );
    }
 
    using( Transaction tx = new Transaction( doc ) )
    {
      tx.Start( "Update CNC Fabrication Export "
        + "History Shared Parameters" );
 
      exportParameters.UpdateExportHistory();
 
      tx.Commit();
    }
    return Result.Succeeded;
  }

CNC fabrication Export History Tracking and Creation of Shared Parameters

You probably noted above that the export history and shared parameter management is handled by a separate ExportParameters class.

The following CNC fabrication export history data is tracked and used to populate the corresponding shared parameters on each exported part:

• CncFabIsExported – a Boolean value showing whether an individual part has ever been exported
• CncFabExportedFirst – timestamp of first export
• CncFabExportedLast – timestamp of most recent export

The ExportParameters class implements the following functionality and public interface methods to fulfil this task:

• Define the user visible export history shared parameter names.
• Store the export history shared parameter definitions.
• GetDefinition – Retrieve the parameter Definition from the given element and parameter name.
• Constructor – Initialise the shared parameter definitions from a given sample element.
• IsValid – Check whether all CNC fabrication export parameter definitions were successfully initialised.
• Add – Add a part element id to the list of successfully exported parts.
• UpdateExportHistory – Update the CNC fabrication export history for the given element.
• UpdateExportHistory – Update the CNC fabrication export history for all stored element ids.
• Create – Create the shared parameters to keep track of the CNC fabrication export history:
• Retrieve shared parameter file name
• Retrieve shared parameter file object
• Create the category set for binding
• Retrieve or create shared parameter group
• Retrieve or create the three parameters

Here is the entire class implementation:

/// <summary>
/// Shared parameters to keep track of 
/// the CNC fabrication export history.
/// </summary>
class ExportParameters
{
  /// <summary>
  /// Define the user visible export 
  /// history shared parameter names.
  /// </summary>
  const string _is_exported = "CncFabIsExported";
  const string _exported_first = "CncFabExportedFirst";
  const string _exported_last = "CncFabExportedLast";
 
  /// <summary>
  /// Store the export history 
  /// shared parameter definitions.
  /// </summary>
  Definition _definition_is_exported = null;
  Definition _definition_exported_first = null;
  Definition _definition_exported_last = null;
 
  Document _doc = null;
  List<ElementId> _ids = null;
 
  /// <summary>
  /// Return the parameter definition from
  /// the given element and parameter name.
  /// </summary>
  static Definition GetDefinition(
    Element e,
    string parameter_name )
  {
    Parameter p = e.get_Parameter(
      parameter_name );
 
    Definition d = ( null == p )
      ? null
      : p.Definition;
 
    return d;
  }
 
  /// <summary>
  /// Initialise the shared parameter definitions
  /// from a given sample element.
  /// </summary>
  public ExportParameters( Element e )
  {
    _definition_is_exported = GetDefinition(
      e, _is_exported );
 
    _definition_exported_first = GetDefinition(
      e, _exported_first );
 
    _definition_exported_last = GetDefinition(
      e, _exported_last );

    if( IsValid )
    {
      _doc = e.Document;
      _ids = new List<ElementId>();
    }
  }
 
  /// <summary>
  /// Check whether all CNC fabrication export 
  /// parameter definitions were successfully 
  /// initialised.
  /// </summary>
  public bool IsValid
  {
    get
    {
      return null != _definition_is_exported
        && null != _definition_exported_first
        && null != _definition_exported_last;
    }
  }
 
  /// <summary>
  /// Add a part element id to the list of
  /// successfully exported parts.
  /// </summary>
  public void Add( ElementId id )
  {
    _ids.Add( id );
  }
 
  /// <summary>
  /// Update the CNC fabrication export 
  /// history for the given element.
  /// </summary>
  void UpdateExportHistory(
    Element e )
  {
    DateTime now = DateTime.Now;
 
    string s = string.Format(
      "{0:4}-{1:02}-{2:02}T{3:02}.{4:02}.{5:02}.{6:03}",
      now.Year, now.Month, now.Day,
      now.Hour, now.Minute, now.Second, now.Millisecond );
 
    s = now.ToString( "yyyy-MM-ddTHH:mm:ss.fff" );
 
    e.get_Parameter( _definition_is_exported )
      .Set( 1 );
 
    Parameter p = e.get_Parameter(
      _definition_exported_first );
 
    string s2 = p.AsString();
 
    if( null == s2 || 0 == s2.Length )
    {
      p.Set( s );
    }
 
    e.get_Parameter( _definition_exported_last )
      .Set( s );
  }
 
  /// <summary>
  /// Update the CNC fabrication export 
  /// history for all stored element ids.
  /// </summary>
  public void UpdateExportHistory()
  {
    foreach( ElementId id in _ids )
    {
      UpdateExportHistory(
        _doc.GetElement( id ) );
    }
  }
 
  /// <summary>
  /// Create the shared parameters to keep track
  /// of the CNC fabrication export history.
  /// </summary>
  public static void Create( Document doc )
  {
    /// <summary>
    /// Shared parameters filename; used only in case
    /// none is set and we need to create the export
    /// history shared parameters.
    /// </summary>
    const string _shared_parameters_filename
      = "export_cnc_fab_shared_parameters.txt";
 
    const string _definition_group_name = "CncFab";
 
    Application app = doc.Application;
 
    // Retrieve shared parameter file name
 
    string sharedParamsFileName
      = app.SharedParametersFilename;
 
    if( null == sharedParamsFileName
      || 0 == sharedParamsFileName.Length )
    {
      string path = Path.GetTempPath();
 
      path = Path.Combine( path,
        _shared_parameters_filename );
 
      StreamWriter stream;
      stream = new StreamWriter( path );
      stream.Close();
 
      app.SharedParametersFilename = path;
 
      sharedParamsFileName
        = app.SharedParametersFilename;
    }
 
    // Retrieve shared parameter file object
 
    DefinitionFile f
      = app.OpenSharedParameterFile();
 
    using( Transaction t = new Transaction( doc ) )
    {
      t.Start( "Create CNC Export Tracking "
        + "Shared Parameters" );
 
      // Create the category set for binding
 
      CategorySet catSet = app.Create.NewCategorySet();
 
      Category cat = doc.Settings.Categories.get_Item(
        BuiltInCategory.OST_Parts );
 
      catSet.Insert( cat );
 
      Binding binding = app.Create.NewInstanceBinding(
        catSet );
 
      // Retrieve or create shared parameter group
 
      DefinitionGroup group
        = f.Groups.get_Item( _definition_group_name )
        ?? f.Groups.Create( _definition_group_name );
 
      // Retrieve or create the three parameters;
      // we could check if they are already bound, 
      // but it looks like Insert will just ignore 
      // them in that case.
 
      Definition definition
        = group.Definitions.get_Item( _is_exported )
        ?? group.Definitions.Create( _is_exported,
          ParameterType.YesNo, true );
 
      doc.ParameterBindings.Insert( definition, binding,
        BuiltInParameterGroup.PG_GENERAL );
 
      definition
        = group.Definitions.get_Item( _exported_first )
        ?? group.Definitions.Create( _exported_first,
          ParameterType.Text, true );
 
      doc.ParameterBindings.Insert( definition, binding,
        BuiltInParameterGroup.PG_GENERAL );
 
      definition
        = group.Definitions.get_Item( _exported_last )
        ?? group.Definitions.Create( _exported_last,
          ParameterType.Text, true );
 
      doc.ParameterBindings.Insert( definition, binding,
        BuiltInParameterGroup.PG_GENERAL );
 
      t.Commit();
    }
  }
}

External Application Implementation

There is nothing very special about the external application implementation.

All it does is present the three buttons to trigger the external commands to create the shared parameters and perform the export to the two supported formats:

In fact, it does do one thing more, namely read the bitmap images for the command button icons and tooltip images from embedded resources.

Here is the complete implementation:

class App : IExternalApplication
{
  public const string Caption
    = "Export to CNC Fabrication";
 
  static string _namespace_prefix
    = typeof( App ).Namespace + ".";
 
  const string _name = "DXF";
  const string _name2 = "SAT";
  const string _name3 = "Create\r\nShared\r\nParameters";
 
  const string _class_name = "CmdDxf";
  const string _class_name2 = "CmdSat";
  const string _class_name3 = "CmdCreateSharedParameters";
 
  const string _tooltip_format
    = "Export to CNC Fabrication in {0} format";
 
  const string _tooltip_long_description_format
    = "Export Revit parts to CNC Fabrication in {0} format.";
 
  /// <summary>
  /// Load a new icon bitmap from embedded resources.
  /// For the BitmapImage, make sure you reference 
  /// WindowsBase and PresentationCore, and import 
  /// the System.Windows.Media.Imaging namespace. 
  /// </summary>
  BitmapImage NewBitmapImage(
    Assembly a,
    string imageName )
  {
    // to read from an external file:
    //return new BitmapImage( new Uri(
    //  Path.Combine( _imageFolder, imageName ) ) );
 
    Stream s = a.GetManifestResourceStream(
      _namespace_prefix + imageName );
 
    BitmapImage img = new BitmapImage();
 
    img.BeginInit();
    img.StreamSource = s;
    img.EndInit();
 
    return img;
  }
 
  public Result OnStartup(
    UIControlledApplication a )
  {
    Assembly exe = Assembly.GetExecutingAssembly();
    string path = exe.Location;
 
    // Create ribbon panel
 
    RibbonPanel p = a.CreateRibbonPanel( Caption );
 
    // Create DXF button
 
    PushButtonData d = new PushButtonData(
      _name, _name, path,
      _namespace_prefix + _class_name );
 
    d.ToolTip = string.Format( _tooltip_format, _name );
    d.Image = NewBitmapImage( exe, "cnc_icon_16x16_size.png" );
    d.LargeImage = NewBitmapImage( exe, "cnc_icon_32x32_size.png" );
    d.LongDescription = string.Format( _tooltip_long_description_format, _name );
    d.ToolTipImage = NewBitmapImage( exe, "cnc_icon_full_size.png" );
 
    p.AddItem( d );
 
    // Create SAT button
 
    d = new PushButtonData(
      _name2, _name2, path,
      _namespace_prefix + _class_name2 );
 
    d.ToolTip = string.Format( _tooltip_format, _name2 );
    d.Image = NewBitmapImage( exe, "cnc_icon_16x16_size.png" );
    d.LargeImage = NewBitmapImage( exe, "cnc_icon_32x32_size.png" );
    d.LongDescription = string.Format( _tooltip_long_description_format, _name2 );
    d.ToolTipImage = NewBitmapImage( exe, "cnc_icon_full_size.png" );
 
    p.AddItem( d );
 
    // Create shared parameters button
 
    d = new PushButtonData(
      _name3, _name3, path,
      _namespace_prefix + _class_name3 );
 
    d.ToolTip
      = "Create shared parameters for tracking export history";
 
    d.LongDescription
      = "Create and bind shared parameters to the "
      + "Parts category for tracking export history:\r\n\r\n"
      + " * CncFabIsExported - Boolean\r\n"
      + " * CncFabExportedFirst - Text timestamp ISO 8601\r\n"
      + " * CncFabExportedLast - Text timestamp ISO 8601";
 
    d.ToolTipImage = NewBitmapImage( exe,
      "cnc_icon_full_size.png" );
 
    p.AddItem( d );
 
    return Result.Succeeded;
  }
 
  public Result OnShutdown( UIControlledApplication a )
  {
    return Result.Succeeded;
  }
}

Download

To enable you explore this for yourself, the current version is available from the ExportCncFab GitHub repository, and the version discussed here is release 2014.0.0.12. Enjoy!

Thinking Outside the Box

For some fabulous and hilarious examples of thinking outside the box, take a look at these test answers that are 100% wrong and totally genius at the same time.

Security, Framing Cross Section Analyser and REX

My topic for today is structural cross section analysis, i.e. determination of the cross section profile of beam, columns, braces, etc., and the various completely different approaches one can take to achieve this.

I also demonstrate how to make use of some of the powerful functionality provided by the REX toolkit without building my entire application on top of the REX framework.

Before getting to that, though, let me mention where we are with the DevDays conference tour:

• DevDays in Milano and security heads-up
• Five structural framing cross section analysis approaches
• Sample FramingXsecAnalyzer implementation for Revit 2012
• Pure Revit API approach
• Using REX without the REX framework
• Cross section analysis using REX
• Migrating from Revit 2012 to Revit 2014
• Obsolete GeoSnoop
• Download

DevDays in Milano and Security

We held our second West European Devday in Milano on Tuesday.

Here is Jim Quanci entertaining his enthralled audience:

One piece of Jim's presentation deals with security. This is an important topic in its own right, of course, and always has been, but the cloud and mobile discussion brings it to people's attention again, so this also discusses the Autodesk trust center and security in the 360 environment. Most of all, though, it highlights the fact that you and your customers need to have a basic understanding of the issue, and somebody in your organisation needs to know a bit more than just the basics.

I think it is so important and Jim's ten-minute overview so effective and refreshing I decided to publish it right here and now:

• Slide deck
• Audio

Something else happened after the conference, travelling...

On Monday, Jim and I were joking that I arrive at the airport gate at the last minute, and it was about time I get burned.

The retribution for that hubris was immediate: I missed the plane from Milano to London, mistaking the gate closing time for the opening time.

I arrived three minutes late, the gate was adamantly closed, and there was nothing I could do – in spite of this being Italy, after all.

A long taxi ride from Linate to Malpensa and a hefty cancellation fee later, I am now gratefully sitting on a different plane, thanking the powers that be for not being harsher to me.

Back to the topic at hand...

Five Structural Framing Cross Section Analysis Approaches

This is actually a topic I have been wanting to write about for a long time now – how to determine the cross section of a structural framing member.

In fact, I implemented a solution (two solutions!) addressing this several years ago, and never got around to publishing.

There are quite a number of different possible approaches to take.

Here is one of several developer queries that prompted this exploration:

Question: A Structural Framing or Structural Column object can be open shape such as T Shape, I Shape or L Shape, or an enclosed shape such as Rectangular Shape, Square Shape or Round Shape.

Does the Revit API provide a way to find out whether a shape is open or enclosed, and what kind of shape it is?

Answer: The Revit API does not provide any direct API method to tell whether a cross section of a structural column or beam is open or closed, or extract its profile.

There are, however, several reliable approaches you can implement yourself based on the functionality provided both by the Revit API itself and the Revit Extensions REX.

You can always access the basic element geometry. The FamilyInstance.GetOriginalGeometry method returns the member geometry before joins, cuts, etc. are applied. There are various ways to calculate the cross section contour of the structural element from that and analyse it to find the best match according to pre-determined internal definitions. In some cases, it may be pretty simple, since you can check for rectangular and round shapes, existence of inner loops, etc.

Here are a few different approaches that come to mind:

1. For structural extrusions, the REX content generator includes a cross section analysis tool providing automatic section recognition functionality:

• The REX SDK
• Extensions for Revit 2012
• REX Content Generator

2. Some families such as gutter, fascia, slab edge, railings, etc., are based on profiles consisting of 2D elements, e.g., lines, arcs, circles, etc. You might be able to use some unofficial element id relationships to access those elements knowing the element id of the family symbol or its profile. They can be used, for example, to determine the relationship between a curtain wall and its panels or between a stacked wall and it basic wall components.

3. From the element, you can retrieve its solid geometry and location line. The profile lines can be determined by intersecting a plane that is perpendicular to the element location line with its solid. I can imagine that the REX content generator does something like this internally, as well.

4. You can set up a section view cutting the framing element perpendicularly using a view perpendicular to the element location line and ask the element for its view-specific geometry, the section view geometry in that specific view. Then, just ignore all lines that are not lying on the view plane and analyse the face loops in the cut plane.

5. Use the ExtrusionAnalyzer – to do so, grab the FamilyInstance GetOriginalGeometry that returns the member geometry before joins, cuts, etc. are applied. For a linear member, using this and then an ExtrusionAnalyzer in the direction of the beam curve yields a reasonably accurate picture of the beam cross-section. An ExtrusionAnalyzer instance is a single-time use object that should be supplied a solid geometry, a plane, and a direction. Based on that input, it calculates a base boundary parallel to the input plane representing the outer boundary of the shadow cast by the solid onto the input plane along the extrusion direction. Note that only the outer boundary is calculated, so any cavities in the cross section will be ignored.

Sample FramingXsecAnalyzer Implementation for Revit 2012

I implemented a sample application named FramingXsecAnalyzer based on Revit 2012 that demonstrates how to achieve the suggestions 1 and 3 above.

As an example of a really simple analysis, it just determines whether a selected beam or column is hollow or not.

The REX cross section analysis tool providing automatic section recognition functionality can be accessed from a 'pure' Revit add-in, in spite of the fact that it is not built on top of the REX framework.

The direct analysis of the element geometry is quite simple, in this case: we simply grab the first best face we find that is perpendicular to the element extrusion direction, i.e. the framing element curve or location line, and check the number of curve edge loops it contains. If it has more than one, we assume it is hollow. Obviously, more complex test might be required, depending on your exact needs.

Pure Revit API Approach

The cross section analysis based on the pure naked Revit API basically requires two steps:

1. Set up a section view cutting the element in question.
2. Retrieve the cut plane faces of the element geometry.

This will give you a number of edge loops. As far as I understand your definition of 'open' and 'closed', all 'open' cross section shapes have one single loop, and 'closed' ones have more, since they consist of an outer and one or more inner loops.

Here is a more detailed description of the steps and source code:

1. Set up a section view cutting the element in question.

How this can be achieved is demonstrated by our venerable CreateViewSection SDK sample. It shows how to generate a section view through the mid point of a linear structural element such as a wall, floor or beam.

Here is a hollow beam that I used to test it on:

It is horizontal and oriented parallel to the Y axis:

The CreateViewSection creates the a section view for it:

The section view displays its geometry including the internal loop for the hollow cavity:

2. Retrieve and analyse the cut plane faces of the element geometry.

Here is some code that demonstrates this, assuming the section view cutting the element is set up as described above:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
 
  Document doc = Util.GetActiveDocument(
    uidoc, false );
 
  if( null == doc )
  {
    return Result.Failed;
  }
 
  // Retrieve pre-selected or 
  // interactively select element 
 
  Selection sel = uidoc.Selection;
 
  int n = sel.Elements.Size;
 
  if( 1 < n )
  {
    Util.InfoMessage( string.Format(
      "{0} element{1} selected. Please select one "
      + "single framing element for cross section "
      + "analysis.",
      n, Util.PluralSuffix( n ) ) );
 
    return Result.Failed;
  }
 
  Element e = null;
 
  if( 0 < n )
  {
    Debug.Assert( 1 == n,
      "we already checked for 1 < n above" );
 
    foreach( Element e2 in sel.Elements )
    {
      e = e2;
    }
  }
  else
  {
    try
    {
      Reference r = sel.PickObject(
        ObjectType.Element,
        "Please pick a framing element "
        + "for cross section analysis." );
 
      e = doc.GetElement( r.ElementId );
    }
    catch( RvtOperationCanceledException )
    {
      return Result.Cancelled;
    }
  }
 
  // Set up section view
 
  //ViewSection viewSection = GetFrontView( e );
 
  // Retrieve element solid
 
  Options opt = app.Create.NewGeometryOptions();
 
  //opt.IncludeNonVisibleObjects = true;
 
  // Cannot set both detail level and view:
  // Autodesk.Revit.Exceptions.InvalidOperationException
  // DetailLevel is already set. When DetailLevel is set 
  // view-specific geometry can't be extracted.
 
  //opt.DetailLevel = DetailLevels.MAX;
 
  View view = doc.ActiveView;
  opt.View = view;
 
  //opt.View = viewSection;
 
  GeometryElement geo = e.get_Geometry( opt );
  GeometryInstance inst = null;
 
  foreach( GeometryObject obj in geo )
  {
    inst = obj as GeometryInstance;
    if( null != inst )
    {
      break;
    }
  }
  if( null == inst )
  {
    Util.InfoMessage( "Sorry, I am unable to retrieve "
      + "the structural framing geometry instance "
      + "from the selected element." );
 
    return Result.Failed;
  }
  Solid solid = null;
 
  //geo = inst.SymbolGeometry;
  geo = inst.GetInstanceGeometry();
 
  foreach( GeometryObject obj in geo )
  {
    solid = obj as Solid;
 
    if( null != solid
      && 0 != solid.Faces.Size )
    {
      break;
    }
  }
 
  // Select the first planar face which is 
  // perpendicular to view direction, i.e. has
  // same normal vector as the view plane.
  // Assuming the cross section is constant,
  // any one will do. We expect two of them.
 
  XYZ viewDir = view.ViewDirection;
 
  PlanarFace crossSection = null;
 
  foreach( Face f in solid.Faces )
  {
    if( f is PlanarFace
      && Util.IsParallel( viewDir,
        ( f as PlanarFace ).Normal ) )
    {
      crossSection = f as PlanarFace;
 
      break;
    }
  }
 
  if( null == crossSection )
  {
    Util.InfoMessage( "Sorry, I am unable to retrieve "
      + "the structural framing cross section." );
 
    return Result.Failed;
  }
 
  EdgeArrayArray eaa = crossSection.EdgeLoops;
 
  n = eaa.Size;
 
  Debug.Print(
    "The selected structural framing element "
    + "cross section section view cut plane "
    + "face has {0} loop{1} and is thus '{2}'.",
    n, Util.PluralSuffix( n ),
    ( 1 == n ? "open" : "closed" ) );
 
  GeoSnoop.ShowCurve( "Solid face directly",
    eaa, AnalyticalDirection.Y );

It performs the following steps:

• Retrieve a pre-selected element or prompt one to be selected.
• Retrieve its geometry and drill down to a non-empty solid.
• Pick the first best face whose normal is parallel to the view direction.

The selected face represents the element cross section.

The number of loops indicates its topology, as explained above.

Here is a result of displaying the retrieved geometry in a custom 2D picture box using the GeoSnoop.ShowCurve method:

Here is the output from the add-in in the Visual Studio debug output window:

The selected structural framing element cross section section view cut plane face has 2 loops and is thus 'closed'.

Cross Section Analysis Using REX without the REX Framework

The REX content generator analysis is based on faces taken directly from the geometry, not the ExtrusionAnalyzer. It takes the GeometryElement and gathers all PlanarFaces according to a specific normal vector, taking the origin into consideration. That determines all loops. Next, the relations between them are determined.

The 'normal' way to use REX is to create a new Revit REX add-in from scratch using the REX add-in wizard.

I chose a different approach, because I wished to add the method to the add-in I already had.

Some additional steps are required to use this functionality independently of the REX module. In REX modules, they are performed automatically.

The REX.ContentGenerator component is not placed in the GAC or Revit directory, so .NET doesn’t know from where it should be loaded. There are several solutions:

• Provide REX.ContentGenerator.LT.dll in the same directory as your ExternalCommand, e.g. by using CopyLocal = true – not recommended.
• Load REX.ContentGenerator.LT at the beginning of ExternalCommand Execution – doable, but you have to know the correct path, which may be problematic.
• Use the Autodesk.Revit.Framework component to resolve assembly – this is a GAC assembly so .NET has no problem finding it.

The third solution is the most welcomed. Here what you should do:

1. Add a reference to Autodesk.Revit.Framework.dll to your project (you can take it from GAC or from "\Program Files\Common Files\Autodesk Shared\Extensions 2014\Framework\Engine\AssemblyCache\Autodesk.REX.Framework.dll").
2. Set copy local to False.
3. Add the code which resolves the assembly, e.g. in the external command Execute method:

  AppDomain.CurrentDomain.AssemblyResolve
    += new ResolveEventHandler( OnAssemblyResolve );

Here is the method definition:

  static System.Reflection.Assembly OnAssemblyResolve(
    object sender,
    ResolveEventArgs args )
  {
    Assembly a = Assembly.GetExecutingAssembly();
 
    return Autodesk.REX.Framework.REXAssemblies
      .Resolve( sender, args, "2014", a );
  }

Note that the converter initialisation must reside in a different method than the subscription to the assembly resolver OnAssemblyResolve, because .NET investigates all methods before execution and will try to resolve the assembly before you register the resolving mechanism, which will cause a crash. The best way to avoid that is to create an additional method and call it separately, so you can register the resolve mechanism first.

Cross Section Analysis Using REX

Once REX is up and running, you have access to its functionality, and you know what classes and properties to query, there is hardly anything at all left to do.

Here is the entire RexXsecAnalyis method that identifies the framing member cross section type:

  /// <summary>
  /// Use REX to analyse element cross section.
  /// This requires a reference to 
  /// REX.ContentGeneratorLT.dll and prior
  /// initialisation of the REX framework.
  /// The converter initialisation must reside in
  /// a different method than the subscription to
  /// the assembly resolver OnAssemblyResolve.
  /// </summary>
  void RexXsecAnalyis(
    ExternalCommandData commandData,
    Element e )
  {
    // Initialise converter
 
    RVTFamilyConverter rvt = new RVTFamilyConverter(
      commandData, true );
 
    // Retrieve family type
 
    REXFamilyType fam = rvt.GetFamily( e,
      ECategoryType.SECTION_PARAM );
 
    // Retrieve section data
 
    REXFamilyType_ParamSection paramSection = fam
      as REXFamilyType_ParamSection;
 
    REXSectionParamDescription parameters
      = paramSection.Parameters;
 
    // Extract dimensions, section type, tapered
    // predicate, etc.
    // If different start and end sections are 
    // required, use DimensionsEnd as well.
 
    REXSectionParamDimensions dimensions = parameters
      .Dimensions;
 
    ESectionType sectionType = parameters
      .SectionType;
 
    bool tapered = parameters.Tapered;
 
    bool start = true;
 
    Contour_Section contour = parameters.GetContour(
      start );
 
    List<ContourCont> shape = contour.Shape;
 
    Debug.Print(
      "The selected structural framing element "
      + "cross section REX section type is "
      + "{0}.", sectionType );
  }

In this case, it prints the following message to the Visual Studio debug output window:

The selected structural framing element cross section REX section type is RECT_HOLLOW.

The REX documentation provides more information, e.g. on how to retrieve instance characteristics like area or moment of inertia. Here is a table of the supported sections with dimensions:

Note: In case of UNKNOWN, please use the contour directly, since no dimensions will be determined.

Migrating from Revit 2012 to Revit 2014

As said, all of my initial exploration of this was based on Revit 2012.

I easily migrated it to Revit 2014, though, and verified that it still works.

Here are all the code differences required for the migration:

Command.cs:

<   e = doc.get_Element( r.ElementId );
>   e = doc.GetElement( r.ElementId );

<   GeometryObjectArray objects = geo.Objects;
>   //GeometryObjectArray objects = geo.Objects;

<   foreach( GeometryObject obj in objects )
>   foreach( GeometryObject obj in geo )

<   objects = geo.Objects;
>   //objects = geo.Objects;

<   foreach( GeometryObject obj in objects )
>   foreach( GeometryObject obj in geo )

GeoSnoop.cs:

<   XYZ p = e.AsCurve().get_EndPoint( 0 );
<   XYZ p = e.AsCurve().GetEndPoint( 0 );

Not that much, is it?

The harder part was to browse to the REX .NET assemblies that I need to reference.

Here are all the Revit and REX .NET assembly references required for Revit 2014:

• Program Files\Autodesk\Revit 2014\RevitAPI.dll
• Program Files\Autodesk\Revit 2014\RevitAPIUI.dll
• Program Files\Common Files\Autodesk Shared\Extensions 2014\Framework\Components\AREXContentGenerator\REX.ContentGeneratorLT.dll
• Program Files\Common Files\Autodesk Shared\Extensions 2014\Framework\Engine\AssemblyCache\Autodesk.REX.Framework.dll

They can easily be listed by searching the C# project file for the DLL file name extension or the HintPath tag:

  grep -i DLL FramingXsecAnalyzer.csproj

The initial test run threw an exception saying "Could not load file or assembly 'REX.ContentGeneratorLT, Version=2014.0.0.2608, Culture=neutral, PublicKeyToken=null' or one of its dependencies. The system cannot find the file specified."

That was resolved when I updated the crucial OnAssemblyResolve method, bumping the version number from 2012 to 2014:

  static System.Reflection.Assembly OnAssemblyResolve(
    object sender,
    ResolveEventArgs args )
  {
    Assembly a = Assembly.GetExecutingAssembly();
 
    return Autodesk.REX.Framework.REXAssemblies
      .Resolve( sender, args, "2014", a );
  }

I tested it on the following tubular column in Revit 2014 instead of a beam:

Here are the two resulting report messages from the pure Revit API and REX analysis, respectively:

The selected structural framing element cross section section view cut plane face has 2 loops and is thus 'closed'.

The selected structural framing element cross section REX section type is TUBE.

Obsolete GeoSnoop

This is actually the origin of the GeoSnoop .NET boundary curve loop visualisation, later updated for use with family symbols, that I make use of in the RoomEditorApp add-in for the simplified cloud-based 2D Revit model editing.

The RoomEditorApp version is significantly cleaned up, though, so please make sure to ignore the obsolete one provided here.

Download

I created a new FramingXsecAnalyzer GitHub repository to host this project, and published the following releases so far:

• 2012.0.0.0 – initial commit for Revit 2012
• 2014.0.0.0 – initial untested migration from Revit 2012 to Revit 2014
• 2014.0.0.1 – verified working functionality in Revit 2014

Nightingale M3U and Denormalized Filename Characters

Here is a post addressing a Mac denormalized filename character issue, music players on Mac and Python file manipulation, so nothing to do with the Revit API.

It appears that Songbird is dead, Nightingale is its successor, and nothing much else is happening on that front, neither now nor ever.

I guess Nightingale will die a natural death too one of these days, but I am still using it so far anyway.

Just like Songbird, Nightingale does not provide any facility to export its playlists in M3U format, or any other way either, for that matter.

The only way that I am aware of to access the playlist data is to copy and paste it through the user interface.

That returns a list of (Artist, Album, Title) triples.

I presented a Python script to generate M3U from Songbird playlist copy and paste data, later updating it to support FLAC as well as MP3.

It works perfectly well for Nightingale also, completely unchanged.

However, it always had a problem on some filenames with simple non-ASCII characters that no amount of twiddling would fix.

I finally found an explanation for that in this thread discussing why Python's glob module and Unix' find command don't recognize non-ASCII: "Mac OS X uses denormalized characters always for filenames on HFS+. Use unicodedata.normalize('NFD', pattern) to denormalize the glob pattern."

I tried it out, and it does indeed fix the problem.

Here is my updated Python script to convert the (Artist, Album, Title) triples to valid local music track filenames to generate a valid M3U playlist:

#!/usr/bin/env python
#
# songbird_to_m3u.py - nightingale playlist to m3u
#
# Convert the file information copied and pasted from
# a songbird or nightingale playlist to an m3u playlist.
#
# Jeremy Tammik, Autodesk Inc., 2013-05-12
#
# Artist, Album, Title -->
# /m/Artist/Album/[Track]*Title.flac
# /m/Artist/Album/[Track]*Title.mp3
#
# cat nightingale_export.txt | songbird_to_m3u.py > playlist.m3u
#
import glob, os, sys, unicodedata

# filenames should be in the system encoding:
#fse = sys.getfilesystemencoding()

nOk = 0
nFailed = 0

while True:
  try: line = raw_input().decode("utf-8")
  except: break

  #print '>', line

  a = line.strip().split( ', ' )

  if 3 != len(a):

    print '#', line, ' - not 3 elements'
    sys.stderr.write( line + ' - not 3 elements\n' )
    nFailed += 1
    continue

  ok = False
  p = u'/m/' + a[0] + u'/' + a[1] + u'/*' + a[2]

  # Mac OS X uses denormalized characters always for
  # filenames on HFS+. Use
  #   unicodedata.normalize('NFD', pattern)
  # to denormalize the glob pattern.
  # http://stackoverflow.com/questions/14185114/pythons-glob-module-and-unix-find-command-dont-recognize-non-ascii

  p = unicodedata.normalize('NFD', p)

  a1 = glob.glob( p + '.flac' )
  if 1 == len(a1):
    print a1[0]
    ok = True
  else:
    a2 = glob.glob( p + '.mp3' )
    if 1 == len(a2):
      print a2[0]
      ok = True

  if ok:
    nOk += 1
  else:
    print '#', p, '?'
    sys.stderr.write(
      '\n%s\n%s\nglob returned %d (flac) and %d (mp3)\n\n'
      % (line, p, len(a1), len(a2)) )
    nFailed += 1

sys.stderr.write(
  '%s files passed, %s failed.\n'
  % (nOk, nFailed) )

Et voila! That's all there is to it.

DevDay@au Chronicle Estorage View Depth Sound of Noise

Monday was the first day at Autodesk University in Las Vegas, dedicated to the forward-looking confidential DevDays conference with the main focus on the rEvolution – where desktop meets the cloud.

In spite of the confidential nature of the information discussed, I am sure I can share an at least an outline of the content here in public with you.

I'll also touch on a couple of other interesting topics that cropped up on the past few days, such as the need to disconnect from central before removing an updater reference, the Autodesk Chronicle product launch, a view depth override macro showing a nice example of making use of Chronicle, and last but not least the sound of noise.

DevDay@AU

The Autodesk Developer Network conference discusses confidential future directions of the products and their APIs.

I'll look in more detail at the following agenda items:

• General Design
• Cloud & mobile platform web service APIs
• Afternoon breakout sessions for AEC, Infrastructure & Manufacturing, Media & Entertainment
• BIM – Architecture, Engineering, Construction and Infrastructure breakout session

This exciting day was wrapped up with the AppHack contest final and a social evening event at El Segundo Sol.

General design

The warm welcome by Jim Quanci was followed by the keynote presentation by Amy Bunsell, VP AutoCAD Products, on AutoCAD evolution on the desktop and connecting to other platforms. We further discussed the Autodesk cloud & mobile platforms, the future direction of AutoCAD and its APIs, and the full spectrum of the new Autodesk cloud & mobile platform web service APIs.

Cloud & mobile platform web service APIs

Here are some of the different web API related topics we covered:

• Authorisation – ADN OAuth samples.
• Federated Identity, e.g. for a customer to sign in to your web service using the Autodesk id.
• Viewing – web viewer demo
• Creation
  • ReCap web API to create 3D models from photos, used e.g. by kubit, BuildIT for mold comparison and twnkls for elevator design based on photos of stairs. The REST API is in pilot right now.
  • Stephen demonstrated a custom AutoCAD 360 app in an iPad using ReCap to generate a 3D model directly in AutoCAD 360 from photos via ReCap.
  • GrabCad hosting AutoCAD 360.
  • Fusion 360 – live on the stage, Jim and Stephen created a rotating link on an axle in one minute and a racing boat catamaran in another ten or so.
• AutoCAD 360 mobile apps: jobshop building, dynamic attribute addition, live collaboration feeds.
• Rendering as a service (RaaS) with a REST API.
• BIM 360 Glue showing a stadium assembled from gigabytes of data from multiple CAD sources, navigate, access attributes, etc., cf. the Glue update and updated ADN DevBlog samples, now also equipped with the dedicated 360 View technical blog by Manu Venugopal.
• BIM 360 Field construction site web based communication and sharing of issues, checklists, tasks, models, photos etc.
• PLM 360 supporting simple processes to quickly and easily build tools for custom reports and administration, with sample code available from the ADN PLM360-API-Samples.

The OAuth, ReCap, Fusion 360, PLM 360, BIM 360 Field and Glue APIs are ready to use, and companies are out there in the AU exhibition hall demonstrating products based on them.

Afternoon Breakout Sessions

In the afternoon, we split up into three separate breakout sessions for:

• BIM – Architecture, Engineering, Construction and Infrastructure
• Manufacturing
• Media & Entertainment

Us Revit add-in developers are obviously most interested in the first of these.

BIM – Architecture, Engineering, Construction and Infrastructure Breakout Session

The BIM and AEC session focused on three main topics:

• The future of Revit and its APIs – pushing the frontiers of BIM beyond building design and creating opportunities for increasingly complex models ready for detailing and fabrication.
• BIM for infrastructure platforms and new web services APIs – create and use intelligent 3D models to plan, design, build, and manage infrastructure. InfraWorks combines 3D modelling and visualisation technologies for desktop, web, and mobile to allow collaboration on infrastructure models in new, exciting and productive ways. Use the new InfraWorks APIs to integrate with your applications and enable fast and easy infrastructure data exchange and interoperability in InfraWorks, Civil 3D, Revit and other Autodesk products.
• BIM 360 Platforms and new web service APIs – BIM in the cloud provides access to common, up-to-date model information anywhere, any time. APIs available now for Autodesk BIM 360 Glue and Autodesk BIM 360 Field, including the new display component API, deep data-sharing between our BIM technologies, roadmap for the future of BIM in the cloud.

Apart from this very full day of forward looking news and visions, here are some further little news items that also piled up in the last few days and I would like to share with you:

Disconnect from Central Before Removing Updater Reference

If you subscribe to a dynamic model updater in a BIM and later open the model in an environment lacking the add-in implementing the updater, Revit may display a warning message that may be confusing or disconcerting to the uninitiated.

I explained how to remove an updater reference way back in the Revit 2011 timeframe, including automating the removal process.

The process described there could be executed in batch mode over all your models, or at least over the ones that you wish to send to customers.

In newer versions of Revit, the updater itself can specify programmatically that no warning should appear if the updater is not found, as explained in the list of what's new in the Revit 2012 API:

Dynamic Update Framework API changes

There are new settings to flag an updater as optional. Optional updaters will not cause prompting the end user when they are opening a document that was modified by that updater but the updater is not currently registered. Optional updaters should be used only when necessary. By default, updaters are non-optional. New methods introduced to support this change are:

• UpdaterRegistry.SetIsUpdaterOptional(UpdaterId id, bool isOptional)
• UpdaterRegistry.RegisterUpdater(UpdaterId id, bool isOptional)
• UpdaterRegistry.RegisterUpdater(UpdaterId id, Document doc, bool isOptional)

New methods were added to access information about currently registered updaters:

• UpdaterRegistry.GetRegisteredUpdaterInfos(Document doc)
• UpdaterRegistry.GetRegisteredUpdaterInfos()

Revit now disallows any calls to UpdaterRegistry from within the Execute() method of an updater. That means any calls to RegistryUpdater(), AddTrigger(), etc. will now throw an exception. The only method of UpdaterRegistry allowed to be called during execution of an updater is UnregisterUpdater(,) but the updater to be unregistered must be not the one currently being executed.

That will not help you with old or existing models, though.

I tested the very simple and logical steps to remove an updater reference on your sample model and they worked absolutely fine for me:

• Open the model in the user interface.
• Select 'continue working and do not warn me again'.
• Save and close the file.

When I reopen the file the next time, the warning is gone.

By the way, you always should disconnect your files from central before sending them to us for testing.

I see the following messages when opening your file:

• 1_central_model_msg.png
• 2_missing_updater.png
• 3_cannot_find_central.png
• 4_save_not_synced.png

After performing the removal described above, the updater warning disappears. On reopening again, I only see the 'cannot find central' message.

The developer responded: "I tried it again and it didn’t work. Then I remembered your comment about detaching from central (sorry about that), did that and tried again. Then it worked."

Motto: disconnect from central to remove an updater.

Autodesk Chronicle Launch

Chronicle is a free technology preview that enables capturing, sharing, and learning from software workflows, currently supporting AutoCAD, Revit, and Inventor.

It is being launched now at AU.

Chronicle consists of a recording utility to capture recordings, and a web site that displays the recordings as Chronicles, interactive video tutorials. The videos can be shared publically or set to private, so that they can be used as internal training materials for a private office or classroom. In essence, Chronicle allows software experts to showcase their expertise and allows other users to view and learn from their real-world expert examples.

The Chronicle Recording Utility captures workflows from within Autodesk products. It records a continuous video screen capture and optionally voice narration. It is also records the timing and details of workflow information, such as the commands, tools, settings, and dialog boxes used during the workflow. Captured data is uploaded to the Chronicle website. An author can publish the Chronicle as public or private, so the desired user group can view a video of the workflow. Additionally, the captured workflow events are displayed on an interactive timeline, enhancing the viewing and learning experience.

Check out Chronicle and start sharing your knowledge today!

View Depth Override Macro and Chronicle Sample

Just by chance, I happened to notice the View Depth Override macro (source) on the Punto Revit blog by Paolo Emilio Serra and his more recent updated 3D version (source) running a macro in perspective mode, currently still work in progress, and thought that might be of interest to others as well. Looks like interesting stuff.

By the way, the demos on those pages are recorded using the preview version of Chronicle, so you can see some nice live examples of that functionality in use.

Sound of Noise

My son Christopher has been actively creating and publishing music on SoundCloud as Allerdings.

One nice little sample is Hydrophonie, created from nothing but natural sounds recorded using a glass of water and some sesame seeds:

Christopher now set up his own Internet presence at SoundOfNoise.

Exciting stuff, and congratulations!

RoomEditorApp Idling and Benchmarking Timer

I solved my two RoomEditorApp Idling issues!

They were especially worrying due to the fact that I am planning to present this application in my Autodesk university class DV1736 on Cloud-Based, Real-Time, Round-Trip, 2D Revit Model Editing on Any Mobile Device.

By the way, you should now enrol in the AU classes you are interested in – unless you already did :-)

Go to the AU class catalogue, sign in, click 'View All Classes', use the filters or keyword search to locate an event you want to schedule and add it to your personal schedule using the scheduling options and blue plus sign.

Here are my four classes, updated from the AU class catalogue preview version:

• DV1736 – Cloud-Based, Real-Time, Round-Trip, 2D Revit Model Editing on Any Mobile Device – This presentation demonstrates real-time, round-trip editing of a simplified 2D rendering of an Autodesk Revit intelligent model on any mobile device with no need to install any additional software whatsoever beyond a web browser. How can this be achieved? A Revit software add-in exports polygon renderings of room boundaries and other elements such as furniture and equipment to a cloud-based repository that is implemented using an Apache CouchDB NoSQL database. On the mobile device, the repository is queried and the data 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 intelligent model in real-time. All of the components used are completely open source, except for Revit itself. This is an advanced class for experienced programmers (handout and slides).
• DV1914 – Revit API Expert Roundtable: Open House on the Factory Floor – Interact with a panel of Autodesk Revit API experts from Autodesk to get answers to your questions and discuss all relevant topics of your choice. If you are writing add-ins for Revit software, then this is the perfect forum to get to know better the people who shape the APIs you work with and to explain your views, ideas, and problems directly face-to-face. Note that prior .NET programming and Revit programming experience is required and that this class is not suitable for beginners (handout and slides).
• DV2010 – Advanced Revit 2014 API Features and Samples – This class focuses on some of the major new Autodesk Revit 2014 API features. We look at API access to the project browser, dockable panels, copy and paste, command launching, the graphics pipeline, schedule formatting, and additions to the view API including demonstration and discussion of sample code. We also provide an overview of all the new Revit 2014 SDK samples. Note that prior .NET and Revit programming experience is required and that this class is not suitable for beginners (handout and slides).
• DV3464-R – Making Revit Add-ins That Cooperate with Worksharing: A Roundtable Session – Are you an Autodesk Revit-based software developer who has run into issues supporting your add-ins in a workshared environment? Have you hit situations where elements can’t be edited or updated due to conflicts? As a followup discussion to “DV1888: Facing the Elephant in the Room: Making Revit Add-ins That Cooperate with Worksharing”, join this roundtable session to further discuss the techniques that are available to developers to operate on workshared models. Bring questions from your own development experience or more detailed questions inspired by the lecture and discuss the possibilities with a group of experienced Revit API developers. Knowledge of C# and Revit API is required, and prior experience with Revit worksharing will be helpful (slides).

Back to my RoomEditorApp, though, and the nitty-gritty details of resolving my Idling issues.

RoomEditorApp Idling Issues

I recently wrote about my updated Revit 2014 version of the RoomEditorApp, the Revit add-in part of my cloud-based real-time round-trip 2D Revit model editing application, the RoomEditorApp GitHub repository and its architecture and external application implementation.

In closing, I mentioned two worrying Idling related problems:

• Unsubscribing from the Idling event had no effect.
• Decreased responsiveness of the Idling event.

Happily, and somewhat surprisingly, I yesterday resolved them both.

The issue with the unsubscription was easy, as I recently discovered and discussed the cause.

I was still worried that I might have to switch back to Revit 2013 for the demo due to the unresponsiveness, however.

Luckily, I thought of adding some benchmarking instrumentation code to find out where the issue was, and that helped find and fix the root cause.

It was my own fault :-)

Here are the steps:

• Fixing the RoomEditorApp Idling unsubscription
• Adding a benchmarking timer
• Benchmarking instrumentation
• Initial benchmarking results and conclusion
• Improving the CouchDB sequence number query
• Twiddling with Idling responsiveness
• Download

Fixing the RoomEditorApp Idling Unsubscription

My attempts to unsubscribe from the Idling event were failing due to the fact that each new external command invocation generates a new different class instance. The unsubscribing instance was therefore providing a different member method to unsubscribe than the original one used to subscribe, so the original just kept going, as explained in the discussion on singleton application versus multiple command instances.

That was really easy to fix, since I only had to modify the external application to keep track of the handler used to subscribe, and reuse that specific stored method delegate when unsubscribing again.

I published the fix in release 2014.0.0.16.

Adding a Benchmarking Timer

While I was at it, I decided to spend at least a little time trying to understand the cause for this unresponsiveness.

But where to start?

Well, first of all, I needed to understand where the time was actually being consumed.

To do so, I looked at my timer code for benchmarking and the JtTimer class that I used to create some filtered element collector benchmarks.

Here is the spruced up version that I ended up using for the following tests:

/// <summary>
/// Performance timer for profiling purposes.
/// For a full description, please refer to
/// http://thebuildingcoder.typepad.com/blog/2010/03/performance-profiling.html
/// </summary>
public class JtTimer : IDisposable
{
  #region Internal TimeRegistry class
  class TimeRegistry
  {
    #region Internal data and helper methods
    class Entry
    {
      public double Time { get; set; }
      public int Calls { get; set; }
    }
 
    static Dictionary<string, Entry> _collection
      = new Dictionary<string, Entry>();
 
    /// <summary>
    /// Return the percentage based on total time.
    /// </summary>
    /// <param name="value">value</param>
    /// <param name="totalTime">total time</param>
    /// <returns></returns>
    static double GetPercent(
      double value,
      double totalTime )
    {
      return 0 == totalTime
        ? 0
        : Math.Round( value * 100 / totalTime, 2 );
    }
    #endregion // Internal data and helper methods
 
    /// <summary>
    /// Add new duration for specified key.
    /// </summary>
    public static void AddTime(
      string key,
      double duration )
    {
      Entry e;
      if( _collection.ContainsKey( key ) )
      {
        e = _collection[key];
      }
      else
      {
        e = new Entry();
        _collection.Add( key, e );
      }
      e.Time += duration;
      ++e.Calls;
    }
 
    /// <summary>
    /// Write the report of the results to a text file.
    /// </summary>
    public static void WriteResults(
      string description,
      double totalTime )
    {
      // Set up text file path:
 
      string strReportPath = Path.Combine(
        Path.GetTempPath(), "PerformanceReport.txt" );
 
      FileStream fs = new FileStream( strReportPath,
        FileMode.OpenOrCreate, FileAccess.Write );
 
      StreamWriter streamWriter = new StreamWriter( fs );
      streamWriter.BaseStream.Seek( 0, SeekOrigin.End );
 
      // Sort output by percentage of total time used:
 
      List<string> lines = new List<string>(
        _collection.Count );
 
      foreach( KeyValuePair<string, Entry> pair
        in _collection )
      {
        Entry e = pair.Value;
 
        lines.Add( string.Format(
          "{0,10:0.00}%{1,10:0.00}{2,8}   {3}",
          GetPercent( e.Time, totalTime ),
          Math.Round( e.Time, 2 ),
          e.Calls,
          pair.Key ) );
      }
      lines.Sort();
 
      string header
        = " Percentage   Seconds   Calls   Process";
 
      int n = Math.Max( header.Length,
        lines.Max<string>( x => x.Length ) );
 
      if( null != description
        && 0 < description.Length )
      {
        n = Math.Max( n, description.Length );
        header = description + "\r\n" + header;
      }
      string separator = "-";
      while( 0 < n-- )
      {
        separator += "-";
      }
      streamWriter.WriteLine( separator );
      streamWriter.WriteLine( header );
      streamWriter.WriteLine( separator );
 
      foreach( string line in lines )
      {
        streamWriter.WriteLine( line );
      }
      streamWriter.WriteLine( separator + "\r\n" );
      streamWriter.Close();
      fs.Close();
      Process.Start( strReportPath );
      _collection.Clear();
    }
  }
  #endregion // Internal TimeRegistry class
 
  string _key;
  Stopwatch _timer;
  double _duration = 0;
 
  /// <summary>
  /// Performance timer constructor.
  /// </summary>
  /// <param name="what_are_we_testing_here">
  /// Key describing code to be timed</param>
  public JtTimer( string what_are_we_testing_here )
  {
    Restart( what_are_we_testing_here );
  }
 
  /// <summary>
  /// Automatic disposal when the the using statement
  /// block finishes: the timer is stopped and the
  /// time is registered.
  /// </summary>
  void IDisposable.Dispose()
  {
    Stop();
  }
 
  /// <summary>
  /// Write and display a report of the timing
  /// results in a text file.
  /// </summary>
  public void Report( string description )
  {
    TimeRegistry.WriteResults(
      description, _duration );
  }
 
  /// <summary>
  /// Restart the measurement from scratch.
  /// </summary>
  public void Restart( string what_are_we_testing_here )
  {
    _key = what_are_we_testing_here;
    _timer = Stopwatch.StartNew();
  }
 
  /// <summary>
  /// Stop the timer.
  /// </summary>
  public void Stop()
  {
    _timer.Stop();
    _duration = _timer.Elapsed.TotalSeconds;
    TimeRegistry.AddTime( _key, _duration );
  }
}

Benchmarking Instrumentation

To use the timer, I equipped various methods of interest with a using call to its constructor, e.g. like this:

  /// <summary>
  /// Return the last sequence number.
  /// </summary>
  public int LastSequenceNumber
  {
    get
    {
      using( JtTimer pt = new JtTimer(
        "LastSequenceNumber" ) )
      {
        ChangeOptions opt = new ChangeOptions();
 
        CouchChanges<DbFurniture> changes
          = _db.GetChanges<DbFurniture>( opt );
 
        CouchChangeResult<DbFurniture> r
          = changes.Results.Last<
            CouchChangeResult<DbFurniture>>();
 
        return r.Sequence;
      }
    }
  }

As you can see, I just add the using statement and a call to the JtTimer constructor to each method I would like to track performance for, nothing else.

All the rest is handled automatically by the JtTimer destructor and other internal methods.

I also added a call to instantiate a top-level timer keeping track of the total time and reporting results each time subscription is started and stopped, respectively, like this:

class App : IExternalApplication
{
  /// <summary>
  /// Subscription debugging timer.
  /// </summary>
  static JtTimer _timer = null;
 
  /// <summary>
  /// Toggle on and off subscription to 
  /// automatic cloud updates.
  /// </summary>
  public static void ToggleSubscription(
    EventHandler<IdlingEventArgs> handler )
  {
    if( Subscribed )
    {
      Debug.Print( "Unsubscribing..." );
      _uiapp.Idling -= _handler;
      _handler = null;
      _buttons[3].ItemText = _subscribe;
      _timer.Stop();
      _timer.Report( "Subscription timing" );
      _timer = null;
      Debug.Print( "Unsubscribed." );
    }
    else
    {
      Debug.Print( "Subscribing..." );
      _uiapp.Idling += handler;
      _handler = handler;
      _buttons[3].ItemText = _unsubscribe;
      _timer = new JtTimer( "Subscription" );
      Debug.Print( "Subscribed." );
    }
  }
 

Here are all the occurrences of the string "JtTimer" in the entire project (copy and paste somewhere or view source to see truncated lines in full):

Find all "JtTimer", Find Results 1, "Entire Solution", "*.cs"
  App.cs(34):           static JtTimer _timer = null;
  App.cs(234):          _timer = new JtTimer( "Subscription" );
  CmdSubscribe.cs(43):  using( JtTimer pt = new JtTimer( "OnIdling" ) )
  DbUpdater.cs(59):     using( JtTimer pt = new JtTimer( "DbUpdater ctor" ) )
  DbUpdater.cs(166):    using( JtTimer pt = new JtTimer( "UpdateBim" ) )
  JtTimer.cs(3):        // JtTimer.cs - performance profiling timer
  JtTimer.cs(25):       public class JtTimer : IDisposable
  JtTimer.cs(157):      public JtTimer( string what_are_we_testing_here )
  Properties\AssemblyInfo.cs(61):  // 2013-11-18 - 2014.0.0.17 - added JtTimer
  RoomEditorDb.cs(24):  using( JtTimer pt = new JtTimer( "RoomEditorDb ctor" ) )
  RoomEditorDb.cs(52):  using( JtTimer pt = new JtTimer( "LastSequenceNumber" ) )
  RoomEditorDb.cs(81):  using( JtTimer pt = new JtTimer( "LastSequenceNumberChanged" ) )
  Matching lines: 12
  Matching files: 6
  Total files searched: 21

Initial Benchmarking Results and Conclusion

In the beginning, I was not stopping the top-level timer properly, so I had no grand total, and therefore no percentages.

The very first result looked like this, with just two timers active, showing that I was headed in the right direction:

------------------------------------------
Subscription timing
 Percentage   Seconds   Calls   Process
------------------------------------------
      0.00%      0.04       1   UpdateBim
      0.00%     41.73     420   OnIdling
------------------------------------------

This already tells me that the Idling event handler is consuming a lot of time, whereas the actual BIM update is quick.

Adding a few more timers here and there starts producing useful results:

---------------------------------------------------
Subscription timing
 Percentage   Seconds   Calls   Process
---------------------------------------------------
      0.00%      0.00       1   DbUpdater ctor
      0.00%      0.05       1   UpdateBim
      0.00%      3.27      51   RoomEditorDb ctor
      0.00%     76.40     480   OnIdling
      0.00%     80.35      49   LastSequenceNumber
---------------------------------------------------

The LastSequenceNumber property is eating up absolutely all the time!

It is called once before we start subscribing to the Idling event, and then from inside the event handler.

All of the Idling event handler time is consumed by calls to this property.

I already showed the method implementation as an example of the benchmarking instrumentation.

Looking more closely at this method, I noted that it retrieves all the furniture documents from the database in order to determine the most recent sequence number. The sequence number is used to afterwards retrieve all database changes that occurred after a certain point.

This call will obviously take longer and longer time the more entries we add to the database.

Improving the CouchDB Sequence Number Query

In the calls made to the LastSequenceNumber property from the Idling event handler, it is used only to check whether any new changes occurred.

At that point, we already have an initial sequence number to start from, and can ask the database to return only changes that occurred after that point in time, using a 'since' argument, e.g. like this:

  /// <summary>
  /// Determine whether the given sequence number
  /// matches the most up-to-date status.
  /// </summary>
  public bool LastSequenceNumberChanged( int since )
  {
    using( JtTimer pt = new JtTimer(
      "LastSequenceNumberChanged" ) )
    {
      ChangeOptions opt = new ChangeOptions();
 
      opt.Since = since;
      opt.IncludeDocs = false;
 
      CouchChanges<DbFurniture> changes
        = _db.GetChanges<DbFurniture>( opt );
 
      CouchChangeResult<DbFurniture> r
        = changes.Results.LastOrDefault<
          CouchChangeResult<DbFurniture>>();
 
      Debug.Assert( null == r || since < r.Sequence,
        "expected monotone growing sequence number" );
 
      return null != r && since < r.Sequence;
    }
  }

Replacing the call to the LastSequenceNumber property by a call to the new LastSequenceNumberChanged method in the Idling event handler shows a huge improvement:

----------------------------------------------------------
Subscription timing
 Percentage   Seconds   Calls   Process
----------------------------------------------------------
      0.00%      0.00       1   DbUpdater ctor
      0.00%      0.11       1   UpdateBim
      0.00%      3.25    1741   RoomEditorDb ctor
      0.00%      5.35       1   LastSequenceNumber
      0.00%     19.79    1738   LastSequenceNumberChanged
      0.00%     23.55    1951   OnIdling
----------------------------------------------------------

Now a much larger number of calls to the RoomEditorDb constructor and the LastSequenceNumberChanged method can be completed in much less time.

The one and only initial call to LastSequenceNumber is still awfully expensive and could probably also be improved, but the LastSequenceNumberChanged method is quick, and the whole Idling handling is immediately much more responsive.

Twiddling with Idling Responsiveness

I added the Stop method to the timer class and call when unsubscribing from Idling, as shown above in the benchmarking instrumentation code.

That switches on the top-level timer providing the 100% measurement and enables the percentage calculations, like this:

----------------------------------------------------------
Subscription timing
 Percentage   Seconds   Calls   Process
----------------------------------------------------------
      0.00%      0.00       1   DbUpdater ctor
      0.25%      0.05       1   UpdateBim
      8.85%      1.67     486   LastSequenceNumberChanged
     16.06%      3.03     489   RoomEditorDb ctor
     17.05%      3.22   48667   OnIdling
     27.89%      5.27       1   LastSequenceNumber
    100.00%     18.89       1   Subscription
----------------------------------------------------------

With a more responsive behaviour, I am able to experiment a bit. For instance, I removed the stopwatch in the Idling event handler again, call SetRaiseWithoutDelay immediately, and ignore 99 out of hundred calls to the Idling event handler. As you can see, the Idling handler is called a hundred times for each check of the LastSequenceNumberChanged property:

----------------------------------------------------------
Subscription timing
 Percentage   Seconds   Calls   Process
----------------------------------------------------------
      0.00%      0.00       2   DbUpdater ctor
      0.11%      0.08       2   UpdateBim
      4.46%      3.23    1693   RoomEditorDb ctor
      8.35%      6.05       1   LastSequenceNumber
     21.72%     15.73    1689   LastSequenceNumberChanged
     27.39%     19.84  168900   OnIdling
    100.00%     72.44       1   Subscription
----------------------------------------------------------

The one single call to the LastSequenceNumber property costs more time than almost 500 calls to LastSequenceNumberChanged and almost 50000 calls to the Idling event handler.

Whew.

Download

This application lives in the RoomEditorApp GitHub repository and the versions discussed above are:

• 2014.0.0.16 with the unsubscription fixed as described in the discussion of singleton application versus multiple command instances.
• 2014.0.0.17 with added benchmarking timer and code, new JtTimer class, RoomEditorDb.LastSequenceNumber identified as the culprit, LastSequenceNumberChanged implemented, which only retrieves new changes and saves a huge amount of time, so the Idling event handling is now responsive and snappy.

I hope that this is of interest to you for numerous reasons.

The most important lesson should be: please benchmark your code!

Localised Unit Abbreviations

I recently discussed how to generate unit abbreviations, both using a hard coded list and automatically generating them from the UnitSymbolType enumeration values.

I implemented the CmdDutAbbreviation command in The Building Coder samples to test these abbreviations, and also enhanced it to display the Display Unit Type to Unit Types mapping that we added in the meantime.

Victor Chekalin, or Виктор Чекалин, reacted to this analysis and adds:

Thank you for your investigation.

But... There is a big 'but' :-)

Your method with UnitSymbolType is not completely suitable for localised applications, e.g. Russian.

As always, I have solved these little issues :-)

You write above: 'After some further digging on the Revit API help file RevitAPI.chm, I discovered the FormatOptions GetValidUnitSymbols method'. But you did not dig deep enough to find the old GetLabelFor method in the static LabelUtils class.

If you looked at that, you'll see that one of overridden method takes UnitSymbolType as parameter.

And guess what it returns?

Right. The localizable abbreviation for Unit Symbol :-) – exactly what we need.

So, the command to retrieve a suitable localised Unit Type abbreviation becomes much simpler – check out http://pastebin.com/ZZ0mVeYE – regards, Victor:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  DisplayUnitType n = DisplayUnitType.DUT_GALLONS_US;
 
  for( DisplayUnitType i = DisplayUnitType
    .DUT_METERS; i < n; ++i )
  {
    var validUnitSymbols = FormatOptions
      .GetValidUnitSymbols( i );
 
    foreach( var validUnitSymbol in validUnitSymbols )
    {
      if( validUnitSymbol != UnitSymbolType.UST_NONE )
      {
        var abbrUnitTypeLabel = LabelUtils.GetLabelFor(
          validUnitSymbol );
 
        Debug.Print( "{0} - {1}", abbrUnitTypeLabel,
          LabelUtils.GetLabelFor( i ) );
      }
    }
  }
  return Result.Succeeded;
}

Jeremy adds: I updated The Building Coder samples and integrated Victor's enhancement to the existing CmdDutAbbreviation command.

The relevant code looks like this now and lists both the official Revit API LabelUtils and hard-coded abbreviations plus the valid unit symbols for the first 26 display unit types:

  MapDutToUt map_dut_to_ut = new MapDutToUt();
 
  DisplayUnitType n
    = DisplayUnitType.DUT_GALLONS_US;
 
  Debug.Print( "Here is a list of the first {0} "
    + "display unit types with official Revit API "
    + "LabelUtils, hard-coded The Building Coder "
    + "abbreviations and valid unit symbols:\n",
    (int) n - 1 );
 
  string unit_types, valid_unit_symbols;
 
  for( DisplayUnitType i = DisplayUnitType
    .DUT_METERS; i < n; ++i )
  {
    List<string> uts = new List<string>(
      map_dut_to_ut[i]
        .Select<UnitType, string>(
          u => u.ToString().Substring( 3 ) ) );
 
    int m = uts.Count;
 
    unit_types = 4 > m
      ? string.Join( ", ", uts )
      : string.Format( "{0}, {1} and {2} more",
        uts[0], uts[1], m - 2 );
 
    valid_unit_symbols = string.Join( ", ",
      FormatOptions.GetValidUnitSymbols( i )
        .Where( u => UnitSymbolType.UST_NONE != u )
        .Select<UnitSymbolType, string>(
          u => LabelUtils.GetLabelFor( u )
            + "/" + Util.UnitSymbolTypeString( u ) ) );
 
    Debug.Print( "{0,6} - {1} - {2}: {3}",
      Util.DisplayUnitTypeAbbreviation[(int) i],
      LabelUtils.GetLabelFor( i ),
      unit_types,
      valid_unit_symbols );
  }

On my system, this generates the following output in the Visual Studio debug output window (copy and paste somewhere or view source to see truncated lines in full):

Here is a list of the first 26 display unit types with
official Revit API LabelUtils, hard-coded The Building
Coder abbreviations and valid unit symbols:

    m - Meters - Length, SheetLength and 19 more: m/m
   cm - Centimeters - Length, SheetLength and 20 more: cm/cm
   mm - Millimeters - Length, SheetLength and 20 more: mm/mm
   ft - Decimal feet - Length, SheetLength and 19 more: '/foot_single_quote, LF/lf
  N/A - Feet and fractional inches - Length, SheetLength and 19 more:
  N/A - Fractional inches - Length, SheetLength and 20 more:
   in - Decimal inches - Length, SheetLength and 20 more: "/inch_double_quote
   ac - Acres - Area, HVAC_CrossSection: acres/acres
   ha - Hectares - Area, HVAC_CrossSection: hectare/hectares
  N/A - Meters and centimeters - Length, SheetLength and 17 more:
  y^3 - Cubic yards - Volume, Piping_Volume: CY/cy
 ft^2 - Square feet - Area, HVAC_CrossSection and 2 more: SF/sf, ft²/ft^2
  m^2 - Square meters - Area, HVAC_CrossSection and 2 more: m²/m^2
 ft^3 - Cubic feet - Volume, Piping_Volume and 2 more: CF/cf, ft³/ft^3
  m^3 - Cubic meters - Volume, Piping_Volume and 2 more: m³/m^3
  deg - Decimal degrees - Angle, SiteAngle, Rotation: °/degree_symbol
  N/A - Degrees minutes seconds - Angle, SiteAngle, Rotation:
  N/A - General - Number:
  N/A - Fixed - Number, HVAC_Factor, Electrical_Demand_Factor:
    % - Percentage - Number, Slope and 4 more: %/percent_sign
 in^2 - Square inches - Area, HVAC_CrossSection and 2 more: in²/in^2
 cm^2 - Square centimeters - Area, HVAC_CrossSection and 2 more: cm²/cm^2
 mm^2 - Square millimeters - Area, HVAC_CrossSection and 2 more: mm²/mm^2
 in^3 - Cubic inches - Volume, Piping_Volume and 2 more: in³/in^3
 cm^3 - Cubic centimeters - Volume, Piping_Volume and 2 more: cm³/cm^3
 mm^3 - Cubic millimeters - Volume, Piping_Volume, Section_Modulus: mm³/mm^3
    l - Liters - Volume, Piping_Volume: L/l

Quite a nice correspondence, I think.

Note that the official Revit API LabelUtils abbreviations are localised, as Victor underlines, whereas the hard-coded ones obviosuly are not.

This discussion once again highlights several aspects:

• The Revit API provides a huge amount of functionality, sometimes more than you expect.
• Some functionality is not always obvious to find.
• The various *Utils classes contain many of these hidden gems, as Rudi likes to point out.

The updated version described above is published as release 2014.0.105.2 and includes the release 2014.0.105.1 Display Unit Type to Unit Types mapping.

Full Moon Celebration

I often take the opportunity of spending a couple of hours enjoying infinite space, time, air, fire, earth, and sometimes water by celebrating the full moon with a little fire on a hill nearby with a good view all around.

I did so last night as well, and it was very nice.

Here is a farewell picture of the full moon early this morning:

Multi-Version Visual Studio Revit Add-In Wizard

Developers often ask how to support multiple versions of a Revit add-in from the same codebase.

Many have implemented solutions for this using various Visual Studio project settings.

Alexander Ignatovich of Investicionnaya Venchurnaya Companiya went one step further and implemented a version of the Visual Studio Revit add-in wizard that automatically generates an add-in skeleton supporting both Revit 2013 and 2014 in the same Visual Studio project.

He is very kindly sharing is with us here, saying:

I have one another thing I want to share. I found very nice way to support both Revit 2013 and Revit 2014. I created a project wizard, based on the Visual Studio Revit 2014 add-in wizards.

Look at the csproj file. There are four build configurations in it:

• Debug
• Release
• Debug2014
• Release2014

First, I used choose tags to determine what reference should be used in the build configuration. Unfortunately, there are some problems with $(ProgramW6432), so I replaced it with C:\Program files.

Secondly, I defined a VERSION2014 compilation constant and add it as an example in Command.cs.

Thirdly, I add copying files to 2013 add-ins folder in post-build event. Unfortunately, I can't use choose tag there – it does not work – so the add-in files are copied to both 2013 and 2014 add-ins folders.

Lastly, StartProgram tags contain the proper Revit executable path for each build configuration.

Many thanks to Alexander for analysing, setting up and sharing this!

Here is an overview of the affected files in the highly recommended kdiff3 file comparison tool:

The differences in Command.cs are purely for testing purposes, reporting what release we compiled for in the Visual Studio debug output window:

The differences in the main template file are pure syntactic sugar, affecting only the user interface display strings.

The only significant changes are the ones that Alexander describes above in the C# project file.

Here is Alexander's Revit2014AddinWizardCs3Ai.zip for you to explore in detail for yourself.

Please note that this version of the wizard lacks the ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch tag that I added to suppress the processor architecture mismatch warning when compiling for Revit 2014.

You could always post-process the resulting project files using my tool to recursively disable the architecture mismatch warning.

Support for Revit Flavours and Additional Assembly References

Alexander added some more details on the CSPROJ file editing:

I think it might be useful to briefly describe *.csproj file, maybe only the "Reference Include" tags for Revit API assemblies.

I specify an absolute path, because my Visual Studio 2010 sometimes does not correctly change the project configuration.

One issue with the references is that everybody has installed a different flavour of Revit. I use the Revit Building Design Suite, which is located in C:\Program Files\Autodesk\Revit 2014 by default, other people may use Revit Architecture, Revit Structure or Revit MEP. The default location of Revit Architecture is C:\Program Files\Autodesk\Revit Architecture 2014, and if there is no Building Design Suite on developers computer, the wizard template files need to be edited, replacing the reference paths in *.csproj.

Furthermore, if you want to reference additional Revit API assemblies, you can do so by adding them to the csproj file. For example, if I want to add the Revit UIFramework assembly, I can open *.csproj in an external editor – my choice is Notepad++ – and add the Revit 2014 version to the Choose - When - ItemGroup tag:

  <Reference Include="UIFramework">
    <HintPath>C:\Program Files\Autodesk\Revit 2014\UIFramework.dll</HintPath>
    <Private>False</Private>
  </Reference>

Similarly, add the Revit 2013 version to the Choose - Otherwise - ItemGroup tag:

  <Reference Include="UIFramework">
    <HintPath>C:\Program Files\Autodesk\Revit 2013\Program\UIFramework.dll</HintPath>
    <Private>False</Private>
  </Reference>

Here is what it looks like:

Today is the Last Day

Before closing, let me point out that we are reaching the end of another week, and today is the deadline for submitting the handouts for my Autodesk University classes. So I will do just that.

Let me also wish you a wonderful weekend.

Intimate Revit Database Exploration with the Python Shell

I keep repeating the importance of being able to explore the Revit database model efficiently to understand what is going on.

This can even be important for end users, and is certainly much more so for developers.

The first and foremost important tool is obviously RevitLookup.

The BipChecker is less important and yet also handy for exploring element parameters.

The disadvantage of these two is that they only explore existing values provided by properties and parameters.

They do not offer much support for evaluating methods or exploring dynamically changing relationships.

This mostly requires active programming, e.g. in the Revit macro environment, or hard-core implementation and debugging of an external add-in.

It would be very nice to be able to interact directly with the Revit database using the API hands-on, interpreted, not compiled or packaged in a static macro.

Well, as we have mentioned several times, you can, twice over, using the Revit Python Shell or Revit Ruby Shell.

We look at the RevitPythonShell below, since we are not as knowledgeable in Ruby as in Python.

Personally, I would actually prefer the Ruby language to Python, though, for its more modern architecture.

To run the tests described below, I downloaded and ran the installer for RevitPythonShell for Revit 2014 (r186) and the IronPython installer.

That was it, no further configuration of any kind required:

Alexander Ignatovich of Investicionnaya Venchurnaya Companiya very kindly describes in more detail how these tools can be used for highly efficient exploration and API testing in the Revit database:

Interactive Revit Database Exploration Using the Revit Python Shell

First of all, about RevitLookup. I don't know what to say about it, except I can't imagine my work without this tool now ;-)

I also explored its source, when I began to work with Revit API and needed to realize some functionality.

I use two good tools that let you not waste time waiting for Revit to load and some project you need to open or create:

• Revit Python Shell
• External Command Listener

These are fantastically effective for API exploration, testing some algorithm parts and preparing complex environment for your add-ins.

I mean, for example, creating thousands of family instances in your test.rvt, changing something that you cannot change manually through the interface, for example, extensible storages entities and so on.

I also created some lightweight tools that can point out some pieces of information about project or its specific elements, related to our products, which also cannot be extracted from the interface. They also help me provide product support.

The criteria for your choices depend only your own practice. I use the Python shell when the script code:

• Should not exceed 1/2 – 2/3 of the screen height.
• Should not use your own assemblies (yes, you can load assemblies and add references in your Python script, but our project contains multiple assemblies with dependences and sometimes they read their configuration files, so it's much quicker to create new project in Visual Studio and use External Command Listener to test some functionality).
• Should not react to Revit events, contains dynamic updaters or failure processing.
• Should prepare the environment for you. In this case the first rule can be ignored.

In other cases I use the External Command Listener (but again, it cannot be used if your code needs to react to events, use dynamic updaters or failure processing).

I like Python. Its syntax is very simple.

If you know any programming language, you can immediately write something on Python, even if all you ever read about it is here in this post.

I'll show some examples of scripts.

So, let's start to explore this tools. Start the extension, copy this script to console and press F5 (copy and paste the following code snippets somewhere or view source to see truncated lines in full):

print "Path:", doc.PathName
if doc.GetWorksharingCentralModelPath() != None:
  print "Central model path:", ModelPathUtils.ConvertModelPathToUserVisiblePath(doc.GetWorksharingCentralModelPath())
else:
  print "The project is not work-sharing"

print dir(uidoc)

for elem in selection:
  print elem, elem.Id

First of all, the script prints RVT path and the path of central file. Practically, it's the first useful lightweight tool in your arsenal. You can quickly copy RVT file and central model paths of an opened project.

Secondly, it prints a list of all properties and methods of Autodesk.Revit.UI.UIDocument, which is sometimes useful.

It uses the pre-defined variable uidoc to access the currently active UIDocument. It is defined like this:

uidoc = __revit__.ActiveUIDocument

The last thing shown in this simple example that I use in 95% of my scripts – iterating through the collection of selected elements.

There is absolutely no magic in the doc, uidoc and selection variables. If you click the Revit Python Shell "Configure..." command and open the InitScript tab, you'll see:

# these commands get executed in the current scope
# of each new shell (but not for canned commands)
import clr
clr.AddReference('RevitAPI')
clr.AddReference('RevitAPIUI')
from Autodesk.Revit.DB import *
from Autodesk.Revit.DB.Architecture import *
from Autodesk.Revit.DB.Analysis import *

uidoc = __revit__.ActiveUIDocument
doc = __revit__.ActiveUIDocument.Document
selection = list(__revit__.ActiveUIDocument.Selection.Elements)
...

This also provides an example of how to add additional references in your scripts, and the C# "using" keyword analogue.

The second very often useful thing is filtering elements from the model:

collector = FilteredElementCollector(doc)
linkedElements = collector
  .OfClass(RevitLinkType).ToElements()

for elem in linkedElements:
  efr = elem.GetExternalFileReference()
  print ModelPathUtils.ConvertModelPathToUserVisiblePath(
    efr.GetAbsolutePath())
  print "---------"

This is simple. Just notice that Python requires no "new" keyword.

So we created a filtered element collector for our opened document, retrieved all RevitLinkType elements and iterated through the elements list.

Let's go deeper and see something more complicated.

Some months ago I needed to prepare some model elements information, grouped by worksets. Back in those fabled times I didn't know how to do it :-)

I noticed that elements in the model have a "work set" parameter, so I selected an element, executed the RevitLookup "Snoop current selection..." command, went to the parameters field, found "work set" parameter, noticed that it has integer value, went to it's definition and found out that its built-in parameter name is ELEM_PARTITION_PARAM.

I deduced that if we get all worksets from model, we can get their elements by using an ElementParameterFilter.

At this point, I went to The Building Coder, searched it for "document workset table" and found the post on the workset API.

I learned that I should use a FilteredWorksetCollector. So let's try:

worksets = FilteredWorksetCollector( doc )
worksets.OfKind( WorksetKind.UserWorkset );

for elem in worksets:
  print elem.Name

We got it! They are not sorted, but remember, we are only exploring to find a way to solve the problem, and it is not the production code.

So, continuing to explore how to retrieve the elements from the model that belong to a specific workset.

Let's write a function that filters elements for a specific workset.

The filtered element "work set" parameter should be equal to the Workset.Id.Integer value. We'll pass it to the function as wId:

def FindElementsByWorkset(wId):
  worksetI = int(BuiltInParameter.ELEM_PARTITION_PARAM) # convert enumeration element to an integer
  worksetE = ElementId(worksetI) # and create element id from it

  provider = ParameterValueProvider(worksetE) # the parameter should be BuiltInParameter.ELEM_PARTITION_PARAM
  evaluator = FilterNumericEquals() # the value should be equal
  rule = FilterIntegerRule(provider, evaluator, wId) # to wId

  parafilter = ElementParameterFilter(rule); # create filter parameter
  collector = FilteredElementCollector(doc) # create collector
  collector.WherePasses(parafilter) # and filter elements

  # iterate through the elements
  for elem in collector:
    print "\t", elem.Id, elem.GetType().Name

This function should be placed before our previous code that retrieves the worksets from the model.

The last thing is to invoke our function in a loop:

for elem in worksets:
  print elem.Name
  FindElementsByWorkset(elem.Id.IntegerValue)

As you can easily imagine, I would have spent much more time if I were forced to restart Revit every time I changed something in this code analogue.

The advantages of using this kind of tools are completely obvious, aren't they?

The remaining examples will cover some non-obvious things, that you would need to search for, when you face them. And you will face them :-)

These things include GUIDs and generic methods. This example shows using such things. It finds an extensible storage schema with a specific name, gets doc.OwnerFamily entity of the schema found and retrieves the "FamilyId" field of Guid type.

from Autodesk.Revit.DB.ExtensibleStorage import *
from System import Guid # you need to import this, when you work with Guids!
for sch in Schema.ListSchemas():
  if sch.SchemaName == "CatalogFamilyInfoEntity": # looking for the schema
    schema = sch
print schema.SchemaName
entity = doc.OwnerFamily.GetEntity(schema)
print entity.IsValid()
print entity.Get[Guid]("FamilyId") # generic method public FieldType Get FieldType (string fieldName)

Another non-obvious thing is creating a new Guid for something. If you already know your Guid value, you may use something like this:

import System
parameterId = System.Guid("0ce6f957-070e-4e1b-8f33-7a9d95cf1142")
print "parameter", doc.ProjectInformation.get_Parameter(parameterId).AsString() # I've got shared parameter with this id in the RVT file, you should use your own Guid

If you want to create an absolutely new Guid:

from System.Guid import NewGuid
print NewGuid()

The (almost) last example shows how to automatically create thousands of family instances of different family types of a specific family. The code is not very good, but it is not the production, it's only for me and I seldom use it. This script will create a layer of rng * rng family instances for each family symbol of specific family:

collector = FilteredElementCollector(doc)
collector.OfCategory(BuiltInCategory.OST_StructuralFraming) # my family in this category, just remove this or change to the category of family you want to place in the document
elems = collector.OfClass(FamilySymbol).ToElements() # we get all family symbols in this category

rng = 80 # 80*80 elements of each family symbol
dist = 5 # distance between elements

t = Transaction(doc, 'Create multiple family instances.')
t.Start()

z = 0
for elem in elems:
  if elem.Family.Name == "Enter your family name here":
    for i in range(0,rng):
      for j in range(0,rng):
        loc = XYZ((i*dist),(j*dist),(z*dist))
        familyInst = doc.Create.NewFamilyInstance(loc, elem, Structure.StructuralType.NonStructural)
    z = z + 1

t.Commit()

Let's end with one additional Python script that demonstrates working with LINQ and enumerations:

from System import *
clr.AddReference("System.Core")
from System.Collections.Generic import *
import System
clr.ImportExtensions(System.Linq)
from System.Linq import Enumerable

def printSubCategories(elem, n):
  tab = ""
  for i in range(1, n):
    tab = tab + "\t"
  print tab, elem.Name, Enum.ToObject(BuiltInCategory, elem.Id.IntegerValue), elem.Id
  for child in elem.SubCategories:
    printSubCategories(child, n + 1)

for elem in Enumerable.ToList[Category](doc.Settings.Categories).OrderBy(lambda x: x.Name):
  print elem.Name, Enum.ToObject(BuiltInCategory, elem.Id.IntegerValue), elem.Id
  printSubCategories(elem, 1)
  print "---"

Very many thanks to Alexander for these nice examples!

I hope that everybody takes this chance to really dig deep into intimate direct API interaction with Revit.

ExportCncFab on GitHub and RevitLookup Update

I am in a hurry, still not finding time to prepare my AU classes, and lots going on.

I published an add-in named ExportWallboard to automatically isolate and export wall parts individually to DXF for CNC fabrication back in March, still for Revit 2013, at the time.

That utility is in use, was renamed to ExportCncFab and has enjoyed some further enhancement since, such as:

• Support for export to SAT as well as DXF
• A beautiful little external application to define a nicer user interface
• Support for per-part export history tracking using shared parameters

The history tracking shared parameters are populated with the following values:

• CncFabIsExported – a Boolean value showing whether an individual part has ever been exported
• CncFabExportedFirst – timestamp of first export
• CncFabExportedLast – timestamp of most recent export

I don't have time to discuss all these enhancements in detail right now, but I wanted to point out their existence and publish the whole thing in its current state on GitHub.

So here, without more ado, is the glorious ExportCncFab GitHub repository sporting the first public Revit 2014 release 2014.0.0.10. Enjoy!

RevitLookup Update

I also published RevitLookup on GitHub and mentioned that some enhancements were already made.

Well, more have been added since by a new contributor Prasadgalle, so we arrived at release 2014.0.0.5. Thank you very much for that, Prasad!

Check it out and please feel free to contribute yourself.

Happy weekend!

RevitLookup on GitHub and Invitation to Collaborate

I sincerely hope that everybody reading this is aware of the power and importance of RevitLookup, has already installed it, and is an avid user.

If you do not know what I am talking about, please read these previous posts on the topic, noting that it was previously named RvtMgdDbg, short for 'Revit managed debugging tool':

• RvtMgdDbg
• Fixing RvtMgdDbg for MEP Connectors
• RvtMgdDbg for Revit 2010
• RevitLookup Update
• Units and RevitLookup
• Getting Started with the Revit API

RevitLookup is currently included in the Revit SDK or Software Developer Kit that can be downloaded from the Revit Developer Centre.

In a comment on the AdnRme sample, Matt Mason of IMAGINiT Technologies suggested hosting it on GitHub instead, to facilitate community enhancements.

I talked this over with the development team and now finally got around to doing it.

RevitLookup GitHub Repository

RevitLookup now lives in its own RevitLookup repository on GitHub.

I already integrated some enhancements for structural models provided by Thomas Fink of SOFiSTiK AG.

I made Matt Mason a collaborator on this project and he added some generic enhancements of his own as well, with no need for me to intervene at all in any way.

The current version on GitHub thus already sports some improvements over the standard SDK one, so I would suggest you upgrade to that right away. Simply clone it to your desktop, compile, and replace your existing .NET assembly DLL with the new one.

Invitation to Collaborate

I am happy to welcome anyone else as well who would like to collaborate on this project.

To begin with, however, to get to know you a little, I would suggest that you use 'Fork & Pull' approach as opposed to the 'Shared Repository' approach, so that I can see what you plan to do.

For details on how to go about this, please look at

• Using Pull Requests
• How to GitHub: Fork, Branch, Track, Squash and Pull Request

Before you can contribute anything at all, of course, you need to discover a problem and fix it.

Here are some words from an old ADN case on such an issue:

Fixing RevitLookup

Question: I have used RevitLookup with Revit Architecture without any problems.

When I use it with Revit Structure it works as long as I do not try to snoop a rebar.

Is there a version of RevitLookup that can snoop rebar elements?

Without a software like RevitLookup it would be very time consuming to learn how to access rebar data.

Answer: You can fix any problems that you encounter in RevitLookup yourself, if you like.

Simply run RevitLookup in the Visual Studio debugger, select the offending Revit element, and see what is causing the problem.

Normally, an exception is thrown, which terminates the operation.

If you add an exception handler around the offending line, then all the other information will still be displayed.

That is a cheap fix and workaround solution.

A better solution, of course, is to implement an improved handling of the problematic element, which is often also quite simple.

I haven discussed several such improvements in the past on the blog, e.g., fixing RevitLookup for MEP connectors.

You have the source. The power is in your hands.

With the new repository in place, any useful enhancements can easily be integrated into the main stream for all to share and enjoy.

Good luck and have fun debugging and enhancing RevitLookup together!

The Dynamo Revit Unit Test Framework

I have repeatedly underlined the importance of unit testing, and recently presented the RvtUnit project enabling the use of the NUnit unit testing tool for Revit add-ins.

The Dynamo team now presents another one; in case you have not already heard of and explored it, Dynamo is an exciting visual programming tool on top of Revit.

The best explanation of Dynamo is provided in the Dynamo GitHub repository. Much of the discussion and suggestions for new features etc., is happening on the github issues page, but there are also interesting discussions, links to the downloads, and blog posts by the Dynamo team on www.dynamobim.org.

The Dynamo team just released a new interesting piece of functionality that can provide a huge benefit to all developers writing code against the Revit API.

It's called the Dynamo Revit Test Framework and enables automated testing of Revit API functionality using isolated Revit sessions. It is used internally for Dynamo testing on top of Revit. Given a bit more love, it could be extended as a generic Revit automation framework. And, because all work being done on Dynamo is open source, the source is available and it's completely free!

To learn more, please visit the Dynamo Revit Test Framework GitHub wiki page.

The Dynamo team really appreciates all feedback on Dynamo as a tool for both developers and non-developers striving to automate Revit. Please let them know if you have any questions about the project.

Using the Built-In Revit AcGe Functionality

Anyone who ever used the AutoCAD API for geometrical purposes must be enamoured with AcGe.

On the other hand, the Revit geometry library is pretty meagre in comparison.

Wouldn't it be nice to be able to use all that powerful AcGe functionality in Revit as well?

Actually, if you take a look at the support DLLs included in the Revit main executable directory, AcGe is obviously present:

  C:\Program Files\Autodesk\Revit 2014 > dir *acge*

    Directory of C:\Program Files\Autodesk\Revit 2014

  02/05/2013  12:52 PM  1,679,688 acge19.dll
  02/05/2013  12:52 PM    501,064 acgex19.dll

    2 File(s)      2,180,752 bytes

Wow. Wouldn't it be nice to be able to access that?

Well, you can, actually.

Here is a small proof of concept created by Florian Schmid of SOFiSTiK AG demonstrating showing the usage of AcGe geometry classes in Revit.

He originally provided it for Revit 2013. I did not get around to testing and verifying it until now, on Revit 2014, so here are the archive files for both of these versions:

• acge_revit_2013.zip
• acge_revit_2014.zip

The latter contains the Visual Studio solution acge_revit.sln that includes three Visual Studio projects:

• geometry_acge – a C++/CLI project that links with acge19.lib. The static Converter class provides methods to convert Revit geometry objects to AcGe objects and vice versa. The Helper class provides two higher level methods for curve projection.
• AcGeTest – a C# project implementing an external application that uses the Geometry.AcGe.Helper.orthoProjectIntoPlane method to project some Revit lines into a plane in its OnStartup method.
• AcGeTestCmd – a C# project implementing an external command providing the same functionality in its Execute mainline.

AcGeTest references the geometry_acge assembly, of course.

The AcGe headers and libs are those from the 2013 ObjectARX or ObjectARX 2014 installations, respectively. There is no need to modify them in any way.

The acge19.dll is automatically demand loaded when geometry_acge.dll is loaded. Because acge19.dll lives in the same location as revit.exe, it is found without problems, so no need to manually load it.

To get the example working, you have to adjust the 'Include Directory' and 'Additional Library Directories' of the geometry_acge project so that the ObjectARX headers and libraries can be found on your system.

Welcome back AcGe, how we’ve missed you!

Here are the steps I performed to install ObjectARX 2014 and migrate the sample to the new version:

• Download and install ObjectARX. For all further information on that and self-help resources for AutoCAD software-based development efforts, please visit the AutoCAD Developer Center, which provides API overviews, getting started presentations, links to API discussion groups and more.
• Update the Revit API assembly references from 2013 to 2014.
• Migrate obsolete code, e.g. calls to NewLineBound, NewLineUnbound and get_EndPoint were replaced by Line.CreateBound, Line.CreateUnbound and GetEndPoint. You might want to take a look at the definition of the Geometry class in the curve_converter.cpp module of the geometry_acge project to see examples of how these calls look in C++.
• Fix the architecture mismatch warning.

The result is an error and warning free compilation (copy and paste somewhere or view source to see truncated lines in full):

------ Rebuild All started: Project: geometry_acge, Configuration: Debug x64 ------
  Stdafx.cpp
  AssemblyInfo.cpp
  curve_converter.cpp
  Generating Code...
  .NETFramework,Version=v4.0.AssemblyAttributes.cpp
  geometry_acge.vcxproj -> C:\a\vs\acge_revit\x64\Debug\geometry_acge.dll
------ Rebuild All started: Project: AcGeTest, Configuration: Debug Any CPU ------
  AcGeTest -> C:\a\vs\x64\AcGeTest.dll
========== Rebuild All: 2 succeeded, 0 failed, 0 skipped ==========

There was one more hiccup: the debug version had an erroneous C++ compilation setting, generating a Multi-threaded Debug DLL. I had to change that to generate a Multi-threaded DLL instead, to ensure that the correct runtime library is used.

Many thanks to Florian for pointing out and demonstrating the access to this powerful geometry functionality.

Disclaimer

Note that I am not sure of the legality of making use of this undocumented access.

If you plan to use this approach in a commercial product, I suggest checking with the appropriate Autodesk channels first.

I also took this opportunity of adding a license and a disclaimer to this blog itself, covering all its contents.

I recently discovered the importance of a license when starting to publish more diligently on GitHub.

Text File Driven Automatic Placement of Family Instances

My colleague Emmanuel Di Giacomo recently asked me for an application to automatically place Revit family instances in a project at a list of X, Y, Z coordinates read from a text file.

A similar add-in was already published for Revit 2011 at Revit Today.

The user interface is minimal:

This form enables the following simple and effective workflow to achieve a lot of functionality in very few lines of code, significantly aided and abetted by the combo box DataSource and the regular expression supported real number parsing functionality:

1. On loading, list all families whose placement type equals FamilyPlacementType.OneLevelBased.
2. On selecting a family, list all its symbols.
3. Prompt the user to select an input text file containing a list of X, Y and Z coordinates.
4. Helper method to parse a string to extract an XYZ point.
5. Parse the input text file.
6. External command mainline and form driver – start a transaction and place instances of the selected family type at all the XYZ points.
7. Conclusion and download.
8. GitHub repository.

On an unrelated topic, we end with some news on BIM 360 Glue.

First, a look at the event handlers and other code implementing the steps above:

1. On Load – List Families

When the form is initially loaded, a filtered element collector retrieves all families in the document.

Since this add-in only supports the simplest form of instance placement and one single overload of the NewFamilyInstance method taking a point, family type and StructuralType argument, we remove all families except the ones whose placement type equals FamilyPlacementType.OneLevelBased:

  private void PlaceInstancesForm_Load(
    object sender,
    EventArgs e )
  {
    List<Family> families = new List<Family>(
      new FilteredElementCollector( _doc )
        .OfClass( typeof( Family ) )
        .Cast<Family>()
        .Where<Family>( f =>
          f.FamilyPlacementType ==
            FamilyPlacementType.OneLevelBased ) );
 
    cmbFamily.DataSource = families;
    cmbFamily.DisplayMember = "Name";
  }

Note how easily and efficiently we can populate the combo box entries using the DataSource property to extract and display the family names to the user.

2. On Selecting a Family – List its Symbols

Each time the selected family changes, the cmbFamily_SelectedIndexChanged event handler updates the list of family symbols it provides.

They are immediately accessible from the Family.Symbols property.

However, the FamilySymbolSet that it returns cannot immediately be passed into the family type combo box DataSource property; it can be passed in after converting it to a generic List instance:

  private void cmbFamily_SelectedIndexChanged(
    object sender,
    EventArgs e )
  {
    ComboBox cb = sender as ComboBox;
 
    Debug.Assert( null != cb,
      "expected a combo box" );
 
    Debug.Assert( cb == cmbFamily,
      "what combo box are you, then?" );
 
    Family f = cb.SelectedItem as Family;
 
    FamilySymbolSet symbols = f.Symbols;
 
    // I have to convert the FamilySymbolSet to a
    // List, or the DataSource assignment will throw 
    // an exception saying "Complex DataBinding 
    // accepts as a data source either an IList or
    // an IListSource.
 
    List<FamilySymbol> symbols2
      = new List<FamilySymbol>(
        symbols.Cast<FamilySymbol>() );
 
    cmbType.DataSource = symbols2;
    cmbType.DisplayMember = "Name";
  }

3. Select an Input Text File

Hmm. Actually, there is absolutely nothing to say about this step. Well, I can mention the methods implementing it.

The Util class provides a method FileSelectTxt to select the input text file:

  /// <summary>
  /// Select a specified 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,
    string title,
    string filter,
    out string filename )
  {
    OpenFileDialog dlg = new OpenFileDialog();
    dlg.Title = title;
    dlg.CheckFileExists = true;
    dlg.CheckPathExists = true;
    dlg.InitialDirectory = folder;
    dlg.Filter = filter;
    bool rc = ( DialogResult.OK == dlg.ShowDialog() );
    filename = dlg.FileName;
    return rc;
  }
 
  /// <summary>
  /// Select a text 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 public bool FileSelectTxt(
    string folder,
    out string filename )
  {
    return FileSelect( folder,
      "Select XYZ coordinate text file or Cancel to Exit",
      "XYZ coordinate text Files (*.txt)|*.txt",
      out filename );
  }

This helper method is called by the browse button click handler, and the selected file path and directory is saved on success:

  private void btnBrowseXyz_Click(
    object sender,
    EventArgs e )
  {
    string filename;
 
    if( Util.FileSelectTxt( _txt_folder_name,
      out filename ) )
    {
      txtFilename.Text = filename;
 
      _txt_folder_name = Path.GetDirectoryName(
        filename );
    }
  }

4. Parse a String for an XYZ Point

I use a regular expression to find and extract real numbers from the lines of text parsed from the selected XYZ input file:

  /// <summary>
  /// A regular expression to match a 
  /// real number with optional leading sign.
  /// </summary>
  const string _one_real_number_regex
    = @"[-+]?[0-9]*\.?[0-9]+";

Initially, I tried using a more complex regular expression to grab all three XYZ coordinates at once, ignoring all intervening characters of any kind whatsoever:

  /// <summary>
  /// A regular expression to match three occurrences
  /// of a real number with optional leading sign.
  /// We gave up using this, because the greedy .*
  /// gobbles the +- sign away from the Y and Z
  /// coordinates.
  /// </summary>
  const string _xyz_real_number_regex
    = @"(?<X>" + _one_real_number_regex + ")"
    + @".*(?<Y>" + _one_real_number_regex + ")"
    + @".*(?<Z>" + _one_real_number_regex + ")";

This does not work well, however, due to the greedy nature of regular expressions, which gobble up as much as they can as soon as possible, for instance removing the preceding +- sign from the Y and Z coordinates.

Furthermore, this forces the user to always enter exactly three coordinates.

By parsing the real numbers one at a time, I can more easily provide support for either two or three coordinates, assuming a zero default Z value.

I pre-compile the regular expression and use it like this in the GetThreeRealNumbers helper method:

  /// <summary>
  /// Static regular expression for 
  /// parsing real numbers.
  /// </summary>
  static Regex _regex = new Regex(
    //_xyz_real_number_regex
    _one_real_number_regex );
 
  /// <summary>
  /// Read three real numbers from the given string
  /// and return true on success. Parse the string s 
  /// for exactly two or three real numbers 
  /// representing the XY or XYZ placement 
  /// coordinates. Z defaults to 0.
  /// </summary>
  static bool GetThreeRealNumbers(
    string s,
    ref double[] xyz )
  {
    int i = 0; // index in string
    int n = 0; // count real numbers found
 
    Match m = _regex.Match( s, i );
 
    // Pure debugging support
 
    foreach( Group g in m.Groups )
    {
      Debug.Print( g.ToString() );
    }
 
    // Read all the real numbers we can get
    // and stop if we find too many
 
    while( 4 > n && m.Success )
    {
      if( 3 > n )
      {
        xyz[n] = double.Parse( m.ToString() );
        i = m.Index + m.Length;
        m = _regex.Match( s, i );
 
        foreach( Group g in m.Groups )
        {
          Debug.Print( g.ToString() );
        }
      }
      ++n;
    }
 
    // Add the default Z coordinate in case of need
 
    if( 2 == n )
    {
      xyz[n++] = 0.0;
    }
 
    // Return success if we found 2 or 3 real numbers
 
    return 3 == n;
  }

5. Parse Input Text File

On confirming the selections made, the input file is read and each line is fed to the GetThreeRealNumbers method.

On success, the three real numbers retrieved are used to populate a Revit XYZ point instance and add it to the list.

Lines beginning with a hash characters are considered comments and ignored.

Each non-comment line that is successfully parsed contributes a point instance to the list of family instance placement coordinates; all other lines are simply ignored:

  private void btnOk_Click(
    object sender,
    EventArgs e )
  {
    StreamReader reader = File.OpenText(
      txtFilename.Text );
 
    string read = reader.ReadToEnd();
 
    string[] lines = read.Split( '\n' );
 
    string s;
    double[] xyz = new double[3] { 0, 0, 0 };
 
    foreach( string line in lines )
    {
      s = line.Trim();
 
      if( s.StartsWith( "#" ) )
      {
        continue;
      }
 
      // Parse string s for exactly two or three
      // real numbers representing the XY or XYZ
      // placement coordinates. Z defaults to 0.
 
      if( GetThreeRealNumbers( s, ref xyz ) )
      {
        XYZ p = new XYZ( xyz[0], xyz[1], xyz[2] );
 
        if( null == _pts )
        {
          _pts = new List<XYZ>( 1 );
        }
        _pts.Add( p );
      }
    }
  }

This leaves plenty of space for you to shoot yourself in the foot, since no warnings are issued if a line does not parse correctly.

We are lenient and expect you to either make no errors or notice them yourself.

6. External Command Mainline and Form Driver – Place Instances of the Selected Family Type

The external command mainline Execute method performs the following tasks:

• Determine the main Revit application window handle to define the form owner.
• Display and handle the place instances form.
• On confirmation, open and commit a transaction in which instances of the selected family type are placed at all XYZ points read from the input file.

  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    IWin32Window revit_window
      = new JtWindowHandle(
        ComponentManager.ApplicationWindow );
 
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Document doc = uidoc.Document;
 
    PlaceInstancesForm f
      = new PlaceInstancesForm( doc );
 
    if( DialogResult.OK == f.ShowDialog(
      revit_window ) )
    {
      using( Transaction t = new Transaction(
        doc ) )
      {
        t.Start( "Place Instances" );
 
        Autodesk.Revit.Creation.Document
          creation_doc = doc.Create;
 
        StructuralType st
          = StructuralType.NonStructural;
 
        foreach( XYZ p in f.Points )
        {
          creation_doc.NewFamilyInstance(
            p, f.Type, st );
        }
 
        t.Commit();
      }
    }
    return Result.Succeeded;
  }

Short and sweet, isn't it?

7. Conclusions and Download

This is rather a lot of useful functionality in rather a few lines of code, I think.

I was especially happy to make use of the DataSource property to directly populate a .NET user interface widget from a filtered element collector.

Well, actually, there is now a tiny amount of LINQ code in between the collector and the data source property. The initial version did not check for the family placement type, and the filtered element collector was used to feed it directly.

To see the whole thing in context and try it out for yourself, here is PlaceInstances05.zip containing the full source code, Visual Studio solution and add-in manifest for the PlaceFamilyInstances external command.

Please be aware that it only supports the simplest kind of family placement requiring a single input point.

Support for curve based, face or element hosted families etc. is left as an exercise to the reader.

Many thanks to Emmanuel for suggesting and testing this.

8. The PlaceInstances GitHub Repository

Better than the direct download above, I repeat my exercise from yesterday creating the MoveDuctJoin GitHub repository.

Here is the new PlaceInstances repository, including the direct link to download the latest version or access this first Revit 2014 release, version 2014.0.0.5.

Actually, I already fixed something after starting to write this article, so the latest current release is now version 2014.0.0.6.

9. BIM 360 Glue API Pilot and Updated Samples

Last but not least, I discussed the BIM 360 Glue viewer and REST API and authentication using Python end of last year.

Mikako Harada now published information on the BIM 360 Glue API pilot and updated samples that you definitely should check out if you have any interest in this area.

This of course ties in quite nicely with the chance to win $5000 in the AppHack contest 2.0...

Move Duct Join Add-In with Video and GitHub Support

I am always happy to take a look at a real MEP issue, so this case caught my eye and prompted me to sit down and do some actual coding again for a change:

Question: How can I programmatically move the join of two ducts, effectively changing their end points?

I do not want to delete and re-enter them because they will normally be connected at the other end as well.

Answer: In general, when working on programmatic manipulation of duct system geometry, you have two options for driving the desired changes:

• Define the ducts, and let Revit automatically insert the required fittings when you ask them to be connected.
• Define the fittings, and let Revit automatically create the required ducts when you ask them to be connected.

This issue is a little bit different, in that all the required components are already present, and you just want to move them around relatively to another.

I took a look at it and implemented an add-in named MoveDuctJoin defining two separate external commands, because they illustrate the different options so clearly:

• CmdDisconnect – this command just moves one duct connector, so the link to the neighbouring duct is broken, causing a disconnect.
• CmdReconnect – this command moves the fitting between the two ducts. That keeps the system connected.

Mini Demo and Some Video Options

To keep things brief, here is a 25 second video that hopefully explains it all:

By the way, since this is so small and short and sweet, I really wanted to embed it inline, which is most easily achieved by converting it to GIF file format.

Camtasia for Windows supports conversion of MP4 to GIF, but Camtasia for Mac does not.

However, I just uploaded it to the Zamzar online converter and received back the converted GIF file result within a minute or two, so that was that.

Oops. Well, maybe not quite. It took a lot longer than that, and the resulting GIF file is 386 MB in size, whereas the original MP4 was smaller than 1 MB. Maybe I won't post it after all. In fact, I even cancelled the download before it finished.

Instead, I uploaded the video to Screencast.com, to compare it with YouTube, which I used in the past.

Here is the result on Screencast.com:

For comparison purposes, here is the same video hosted on YouTube:

Actually, I find the latter slightly handier, so far.

I wish either of them would scale up the video, or at least pad it in white and not waste all that space with the huge black border around it.

External Command User Interaction

The user interaction of both external commands consists of exactly three clicks:

• Launch the command.
• Click a duct close to the source connector to be relocated.
• Pick another point on the duct close to the target point to move it to.

Just for the sake of completeness, or in case the videos above do not display correctly, here are three screen snapshots showing the original situation and the result of running CmdDisconnect and CmdReconnect on it, respectively:

As said, CmdDisconnect just moves the connector of the selected duct, breaking its link to the neighbouring fitting:

CmdReconnect moves the fitting instead, retaining its links to both neighbouring ducts:

Now let's look at how that is implemented, and the similarities and differences between the two approaches.

CmdDisconnect – Move the Connector

The differences between the two commands are very small, so most of the code is duplicated, I'm afraid.

CmdDisconnect implements the following steps:

• Prompt user to pick duct close to the source connector to be moved.
• Prompt user to pick target point on duct to move it to.
• Determine the connector object closest to first point.
• Project the second point onto the duct centre line.
• Move the connector to the projected target point.

The first four items are reused unchanged for the other command as well.

Only the last item does any real work and thus requires a transaction:

/// <summary>
/// External command to move a duct connector 
/// away from its original position along the
/// duct centre line, disconnecting from the
/// neighbour element.
/// </summary>
[Transaction( TransactionMode.Manual )]
public class CmdDisconnect : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Document doc = uidoc.Document;
    Selection sel = uidoc.Selection;
    Duct duct = null;
    XYZ pFrom = null;
    XYZ pTo = null;
 
    try
    {
      Reference r = sel.PickObject(
        ObjectType.Element,
        new DuctSelectionFilter(),
        "Please pick a duct at the "
        + "connection to move." );
 
      duct = doc.GetElement( r.ElementId ) as Duct;
      pFrom = r.GlobalPoint;
 
      r = sel.PickObject(
        ObjectType.Element,
        new DuctSelectionFilter(),
        "Please pick a target point on the "
        + "duct to move the connection to." );
 
      pTo = r.GlobalPoint;
    }
    catch( Autodesk.Revit.Exceptions
      .OperationCanceledException )
    {
      return Result.Cancelled;
    }
 
    // Determine connector closest to picked point
 
    ConnectorSet connectors
      = duct.ConnectorManager.Connectors;
 
    Connector con = null;
    double d, dmin = double.MaxValue;
 
    foreach( Connector c in connectors )
    {
      d = pFrom.DistanceTo( c.Origin );
 
      if( d < dmin )
      {
        dmin = d;
        con = c;
      }
    }
 
    // Determine target point to move it to
 
    Transform cs = con.CoordinateSystem;
 
    Debug.Assert(
      con.Origin.IsAlmostEqualTo( cs.Origin ),
      "expected same origin" );
 
    Line line = Line.CreateUnbound( cs.Origin, cs.BasisZ );
 
    IntersectionResult ir = line.Project( pTo );
 
    pTo = ir.XYZPoint;
 
    Debug.Assert( line.Distance( pTo ) < 1e-9,
      "expected projected point on line" );
 
    // Modify document within a transaction
 
    using( Transaction tx = new Transaction( doc ) )
    {
      tx.Start( "Move Duct Connector" );
      con.Origin = pTo;
      tx.Commit();
    }
    return Result.Succeeded;
  }
}

CmdReconnect – Move the Fitting

CmdReconnect implements the following steps, which include the first four from above unchanged:

• Prompt user to pick duct close to the source connector to be moved.
• Prompt user to pick target point on duct to move it to.
• Determine the connector object closest to first point.
• Project the second point onto the duct centre line.
• Determine translation vector from the source to the projected target point.
• Determine the neighbouring fitting.
• Move the fitting to the projected target point.

We access the neighbouring fitting by first retrieving one of its connectors, which is connected to the duct one closest to the first picked point. The fitting element itself is then provided by the Connector.Owner property.

This is achieved using the GetConnectedConnector method adapted from the TraversalTree.cs module of the TraverseSystem SDK sample:

  /// <summary>
  /// Return the connector 
  /// connected to the one given.
  /// </summary>
  static Connector GetConnectedConnector(
    Connector con )
  {
    Connector neighbour = null;
 
    int ownerId = con.Owner.Id.IntegerValue;
 
    ConnectorSet refs = con.AllRefs;
 
    foreach( Connector c in refs )
    {
      // Ignore non-End connectors and  
      // connectors on the same element
 
      if( c.ConnectorType == ConnectorType.End
        && !ownerId.Equals(
          c.Owner.Id.IntegerValue ) )
      {
        neighbour = c;
        break;
      }
    }
    return neighbour;
  }

With that in place, the rest of the command implementation looks like this:

/// <summary>
/// External command to move a duct connector 
/// away from its original position along the
/// duct centre line, disconnecting from the
/// neighbour element.
/// </summary>
[Transaction( TransactionMode.Manual )]
public class CmdReconnect : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Document doc = uidoc.Document;
    Selection sel = uidoc.Selection;
    Duct duct = null;
    XYZ pFrom = null;
    XYZ pTo = null;
 
    try
    {
      Reference r = sel.PickObject(
        ObjectType.Element,
        new DuctSelectionFilter(),
        "Please pick a duct at the "
        + "connection to move." );
 
      duct = doc.GetElement( r.ElementId ) as Duct;
      pFrom = r.GlobalPoint;
 
      r = sel.PickObject(
        ObjectType.Element,
        new DuctSelectionFilter(),
        "Please pick a target point on the "
        + "duct to move the connection to." );
 
      pTo = r.GlobalPoint;
    }
    catch( Autodesk.Revit.Exceptions
      .OperationCanceledException )
    {
      return Result.Cancelled;
    }
 
    // Determine connector closest to picked point
 
    ConnectorSet connectors
      = duct.ConnectorManager.Connectors;
 
    Connector con = null;
    double d, dmin = double.MaxValue;
 
    foreach( Connector c in connectors )
    {
      d = pFrom.DistanceTo( c.Origin );
 
      if( d < dmin )
      {
        dmin = d;
        con = c;
      }
    }
 
    // Determine target point to move it to
 
    Transform cs = con.CoordinateSystem;
 
    Debug.Assert(
      con.Origin.IsAlmostEqualTo( cs.Origin ),
      "expected same origin" );
 
    Line line = Line.CreateUnbound( cs.Origin, cs.BasisZ );
 
    IntersectionResult ir = line.Project( pTo );
 
    pTo = ir.XYZPoint;
 
    Debug.Assert( line.Distance( pTo ) < 1e-9,
      "expected projected point on line" );
 
    // Determine translation vector
 
    XYZ v = pTo - pFrom;
 
    // Determine neighbouring fitting connector
 
    Connector neighbour
      = GetConnectedConnector( con );
 
    // Modify document within a transaction
 
    using( Transaction tx = new Transaction( doc ) )
    {
      tx.Start( "Move Fitting" );
 
      ElementTransformUtils.MoveElement(
        doc, neighbour.Owner.Id, v );
 
      tx.Commit();
    }
    return Result.Succeeded;
  }
}

Note the similarities and differences between the two commands, and their different effects.

The MoveDuctJoin GitHub Repository

At this point, I would normally be attaching the complete project including source code, Visual Studio solution and add-in manifest as an archive file.

For the first time, however, I am doing the right thing instead, which means creating a GitHub repository for it and not forgetting to attach a license.

Here are the steps I performed to create and properly populate the MoveDuctJoin GitHub repository:

1. Create a new repository on GitHub and initialise it with a readme, license and C# .gitignore file.
2. Clone it to the local system:

   git clone repository_url
   

3. Add all the add-in source files to it:

   git add .
   

4. Commit the changes, optionally preconfiguring your user name and email address:

   git commit
   

5. Push the changes back to the server:

   /v/C/a/vs/MoveDuctJoin/ $ git push
   Username for 'https://github.com': jeremytammik
   Password for 'https://jeremytammik@github.com':
   Counting objects: 13, done.
   Delta compression using up to 8 threads.
   Compressing objects: 100% (10/10), done.
   Writing objects: 100% (11/11), 5.26 KiB, done.
   Total 11 (delta 0), reused 0 (delta 0)
   To https://github.com/jeremytammik/MoveDuctJoin
      944fbf8..7eb010f  master -> master
   

There you are. You now have the MoveDuctJoin repository, including the direct link to download the latest version.

Keeping in mind our future generations, as discussed yesterday on branching and tagging, I also created an official first Revit 2014 release of it, version 2014.0.0.0, in case somebody wants to retrieve that specific release sometime later on.

Room Neighbours

Let's say hello to our neighbours.

This issue was raised and also solved by Erik Eriksson of White Arkitketer AB, who wishes to determine the neighbouring rooms for any given room.

It is an extension of the very early discussion of room and wall adjacency from January 2009 that just looks at determining the neighbouring walls for a given room.

The Revit API now provides much more powerful tools for this kind of analysis, enabling us to easily go the one step further and find out what the neighbouring room is on the other side of each wall.

In the sample code presented below, this analysis is only performed in the wall midpoint. It could easily be extended, though, to determine multiple neighbouring rooms on the other side, splitting the wall location line into a separate interval for each.

Question: I'm trying to find rooms adjacent to other rooms.

Basically the pseudocode would be something like this:

• Get all the rooms in the document.
• For each room, find all adjacent rooms (i.e. the room on the other side of the wall) and the wall separating them.

Is there any method for finding adjacent rooms? First I was thinking about ReferenceIntersector, but that doesn't work on rooms, right?

Then I was thinking about using the Room.IsPointInRoom method and providing it with a point that I project out from the wall, but this means iterating over all the rooms for each of the walls for each room. That feels like it's going to take a while for a large project; for instance, given 1000 rooms with 6 walls each would require 6 000 000 iterations.

Answer: The API does not provide any direct method for obtaining neighbouring rooms.

What you suggest sounds like a good starting point for further analysis to me.

What you need is basically a sort of graph structure.

You could partition the entire 2D plane on any given level into polygons that fall into one of three classes: within a room, within a wall, or outside the building. If you then shrink away the walls, all the neighbouring room polygons of any given room are its adjacent rooms.

If you had a 2D geometry library which automatically generated a graph of neighbouring polygons for you, that might be an attractive and reliable way to go.

How to obtain this data most efficiently without going through the 2D geometrical analysis is not obvious to me either.

The Room.IsPointInRoom method that you suggest is definitely not a very good candidate, though, since, as you say, it requires you to know which room you are looking for in advance, or test all rooms, as you suggest, a really bad idea. You could also limit the rooms to test to the immediate vicinity of the target room, which would improve performance tremendously, of course.

A much more efficient algorithm could be based on the Document.GetRoomAtPoint method instead, using points projected out of the target room through the bounding walls a certain small distance into the neighbouring space, because that just requires the input point, not a room, and gives you the neighbouring room.

One open question is how to decide the number of attempts to make to find different neighbouring rooms on the other side of any one given wall.

You always know that your rooms are larger than a certain minimum size, because you can simply iterate over them all and find out what the smallest width or height of any room is.

Therefore, you know that you only need to perform the 'project point through wall and determine neighbour from GetRoomAtPoint' at points at a certain given distance, e.g. every 50 cm or so.

This is assuming that you do not have really crazily shaped rooms, such as lots of wedges which all meet at a central small circular room, which then might have a large number of neighbours at arbitrarily small distances around its one and only circular wall.

Here are some related discussions:

• Room and wall adjacency
• Room and wall adjacent area
• Space adjacency for heat load calculation

Response: The get room at point method worked great!

I go through all the boundary segments of all the rooms and see if there is a room on the other side.

Here is the method that I use to find the room on the other side at the midpoint of a boundary segment:

  /// <summary>
  /// Return the neighbouring room to the given one
  /// on the other side of the midpoint of the given
  /// boundary segment.
  /// </summary>
  Room GetRoomNeighbourAt(
    BoundarySegment bs,
    Room r )
  {
    Document doc = r.Document;
 
    Wall w = bs.Element as Wall;
 
    double wallThickness = w.Width;
 
    double wallLength = ( w.Location as
      LocationCurve ).Curve.Length;
 
    Transform derivatives = bs.Curve
      .ComputeDerivatives(  0.5, true );
 
    XYZ midPoint = derivatives.Origin;
 
    Debug.Assert(
      midPoint.IsAlmostEqualTo(
        bs.Curve.Evaluate( 0.5, true ) ),
      "expected same result from Evaluate and derivatives" );
 
    XYZ tangent = derivatives.BasisX.Normalize();
 
    XYZ normal = new XYZ( tangent.Y,
      tangent.X * ( -1 ), tangent.Z );
 
    XYZ p = midPoint + wallThickness * normal;
 
    Room otherRoom = doc.GetRoomAtPoint( p );
 
    if( null != otherRoom )
    {
      if( otherRoom.Id == r.Id )
      {
        normal = new XYZ( tangent.Y * ( -1 ),
          tangent.X, tangent.Z );
 
        p = midPoint + wallThickness * normal;
 
        otherRoom = doc.GetRoomAtPoint( p );
 
        Debug.Assert( null == otherRoom
            || otherRoom.Id != r.Id,
          "expected different room on other side" );
      }
    }
    return otherRoom;
  }

The if-statement makes sure that I'm looking in the correct direction with regard to the wall direction. I reverse the vector if the first attempt returns the same room as the one I already have.

Many thanks to Erik for the discussion and solution to this question!

Room Neighbour External Command

I added this code to The Building Coder samples as a new command CmdRoomNeighbours.

It reports the neighbouring rooms at the midpoints of all the boundary segments of a user-selected set of rooms.

JtSelectorMulti – a Generic Multiple Pre- and Post-Selector Class

The selection process supports both pre- and post-selection. You can optionally select the rooms before launching the command. If you do not, you will be prompted to do so interactively by the command itself.

Since I repeatedly mentioned that quite a number of lines of code are required to support pre- and post-selection, I decided to package that into a separate class and implemented a generic templated JtSelectorMulti class for the selection of multiple elements.

It is templated by the type of element to select. You can also specify the required built-in category (or null for none) and a freely definable filtering method.

Using that, the pre- and post-selection support in the external command Execute method mainline now just requires these three statements:

  // Interactively select elements of type Room,
  // either via pre-selection before launching the
  // command, or interactively via post-selection.
 
  JtSelectorMulti<Room> selector
    = new JtSelectorMulti<Room>(
      uidoc, BuiltInCategory.OST_Rooms, "room",
      e => e is Room );
 
  if( selector.IsEmpty )
  {
    return selector.ShowResult();
  }
 
  IList<Room> rooms = selector.Selected;

Here is the class implementation including some comments:

/// <summary>
/// Select multiple elements of the same type using
/// either pre-selection, before launching the 
/// command, or post-selection, afterwards.
/// The element type is determined by the template 
/// parameter. A filtering method must be provided
/// and is reused for both testing the pre-selection
/// and defining allowable elements for the post-
/// selection.
/// </summary>
class JtSelectorMulti<T> where T : Element
{
  /// <summary>
  /// Error message in case of invalid pre-selection.
  /// </summary>
  const string _usage_error = "Please pre-select "
    + "only {0}s before launching this command.";
 
  /// <summary>
  /// Determine whether the given element is a valid 
  /// selectable object. The method passed in is 
  /// reused for both the interactive selection
  /// filter and the pre-selection validation.
  /// See below for a sample method.
  /// </summary>
  public delegate bool IsSelectable( Element e );
 
  #region Sample common filtering helper method
  /// <summary>
  /// Determine whether the given element is valid.
  /// This specific implementation requires a family 
  /// instance element of the furniture category 
  /// belonging to the named family.
  /// </summary>
  static public bool IsTable( Element e )
  {
    bool rc = false;
 
    Category cat = e.Category;
 
    if( null != cat )
    {
      if( cat.Id.IntegerValue.Equals(
        (int) BuiltInCategory.OST_Furniture ) )
      {
        FamilyInstance fi = e as FamilyInstance;
 
        if( null != fi )
        {
          string fname = fi.Symbol.Family.Name;
 
          rc = fname.Equals( "SampleTableFamilyName" );
        }
      }
    }
    return rc;
  }
  #endregion // Common filtering helper method
 
  #region JtSelectionFilter
  class JtSelectionFilter : ISelectionFilter
  {
    Type _t;
    BuiltInCategory? _bic;
    IsSelectable _f;
 
    public JtSelectionFilter(
      Type t,
      BuiltInCategory? bic,
      IsSelectable f )
    {
      _t = t;
      _bic = bic;
      _f = f;
    }
 
    bool HasBic( Element e )
    {
      return null == _bic
        || (null != e.Category
          && e.Category.Id.IntegerValue.Equals(
            (int) _bic ));
    }
 
    public bool AllowElement( Element e )
    {
      return e is T
        && HasBic( e )
        && _f( e );
    }
 
    public bool AllowReference( Reference r, XYZ p )
    {
      return true;
    }
  }
  #endregion // JtSelectionFilter
 
  List<T> _selected;
  string _msg;
  Result _result;
 
  /// <summary>
  /// Instantiate and run element selector.
  /// </summary>
  /// <param name="uidoc">UIDocument.</param>
  /// <param name="bic">Built-in category or null.</param>
  /// <param name="description">Description of the elements to select.</param>
  /// <param name="f">Validation method.</param>
  public JtSelectorMulti(
    UIDocument uidoc,
    BuiltInCategory? bic,
    string description,
    IsSelectable f )
  {
    _selected = null;
    _msg = null;
 
    Document doc = uidoc.Document;
 
    if( null == doc )
    {
      _msg = "Please run this command in a valid"
        + " Revit project document.";
      _result = Result.Failed;
    }
 
    // Check for pre-selected elements
 
    Selection sel = uidoc.Selection;
 
    int n = sel.Elements.Size;
 
    if( 0 < n )
    {
      foreach( Element e in sel.Elements )
      {
        if( !f( e ) )
        {
          _msg = string.Format(
            _usage_error, description );
 
          _result = Result.Failed;
        }
 
        if( null == _selected )
        {
          _selected = new List<T>( n );
        }
 
        _selected.Add( e as T );
      }
    }
 
    // If no elements were pre-selected, 
    // prompt for post-selection
 
    if( null == _selected
      || 0 == _selected.Count )
    {
      IList<Reference> refs = null;
 
      try
      {
        refs = sel.PickObjects(
          ObjectType.Element,
          new JtSelectionFilter( typeof( T ), bic, f ),
          string.Format(
            "Please select {0}s.",
            description ) );
      }
      catch( Autodesk.Revit.Exceptions
        .OperationCanceledException )
      {
        _result = Result.Cancelled;
      }
 
      if( null != refs && 0 < refs.Count )
      {
        _selected = new List<T>(
          refs.Select<Reference, T>(
            r => doc.GetElement( r.ElementId )
              as T ) );
      }
    }
 
    Debug.Assert(
      null == _selected || 0 < _selected.Count,
      "ensure we return only non-empty collections" );
 
    _result = ( null == _selected )
      ? Result.Cancelled
      : Result.Succeeded;
  }
 
  /// <summary>
  /// Return true if nothing was selected.
  /// </summary>
  public bool IsEmpty
  {
    get
    {
      return null == _selected
        || 0 == _selected.Count;
    }
  }
 
  /// <summary>
  /// Return the cancellation or failure code
  /// to Revit and display a message if there
  /// is anything to say.
  /// </summary>
  public Result ShowResult()
  {
    if( Result.Failed == _result )
    {
      Debug.Assert( 0 < _msg.Length,
        "expected a non-empty error message" );
 
      Util.ErrorMsg( _msg );
    }
    return _result;
  }
 
  /// <summary>
  /// Return selected elements or null.
  /// </summary>
  public IList<T> Selected
  {
    get
    {
      return _selected;
    }
  }
}

CmdRoomNeighbours External Command Mainline

Making use of the JtSelectorMulti pre- and post-selection and the GetRoomNeighbourAt method to list the results, here is the complete code of the external command mainline.

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Document doc = uidoc.Document;
 
  // Interactively select elements of type Room,
  // either via pre-selection before launching the
  // command, or interactively via post-selection.
 
  JtSelectorMulti<Room> selector
    = new JtSelectorMulti<Room>(
      uidoc, BuiltInCategory.OST_Rooms, "room",
      e => e is Room );
 
  if( selector.IsEmpty )
  {
    return selector.ShowResult();
  }
 
  IList<Room> rooms = selector.Selected;
 
  List<string> msg = new List<string>();
 
  int n = rooms.Count;
 
  msg.Add( string.Format(
    "{0} room{1} selected{2}\r\n",
    n, Util.PluralSuffix( n ),
    Util.DotOrColon( n ) ) );
 
  SpatialElementBoundaryOptions opt
    = new SpatialElementBoundaryOptions();
 
  IList<IList<BoundarySegment>> loops;
 
  Room neighbour;
  int i = 0, j, k;
 
  foreach( Room room in rooms )
  {
    ++i;
 
    loops = room.GetBoundarySegments( opt );
 
    n = loops.Count;
 
    msg.Add( string.Format(
      "{0}. {1} has {2} loop{3}{4}",
      i, Util.ElementDescription( room ),
      n, Util.PluralSuffix( n ),
      Util.DotOrColon( n ) ) );
 
    j = 0;
 
    foreach( IList<BoundarySegment> loop in loops )
    {
      ++j;
 
      n = loop.Count;
 
      msg.Add( string.Format(
        "  {0}. Loop has {1} boundary segment{2}{3}",
        j, n, Util.PluralSuffix( n ),
        Util.DotOrColon( n ) ) );
 
      k = 0;
 
      foreach( BoundarySegment seg in loop )
      {
        ++k;
 
        neighbour = GetRoomNeighbourAt( seg, room );
 
        msg.Add( string.Format(
          "    {0}. Boundary segment has neighbour {1}",
          k,
          (null==neighbour
            ? "<nil>"
            : Util.ElementDescription( neighbour )) ) );
      }
    }
  }
 
  Util.InfoMsg2( "Room Neighbours",
    string.Join( "\n", msg.ToArray() ) );
 
  return Result.Succeeded;

We use read-only transaction mode for this command, since no database modifications are required.

Sample Run and Download

I tested the command selecting room 5 in the following simplistic model:

Its neighbouring rooms are listed in a message box and in the Visual Studio debug output window, which reports:

Room Neighbours

1 room selected:

1. Room Rooms <197109 Room 5> has 1 loop:
  1. Loop has 4 boundary segments:
    1. Boundary segment has neighbour <nil>
    2. Boundary segment has neighbour Room Rooms <197103 Room 3>
    3. Boundary segment has neighbour Room Rooms <197112 Room 6>
    4. Boundary segment has neighbour Room Rooms <197115 Room 7>

Here is version 2014.0.103.0 of The Building Coder samples source code, Visual Studio solution and RvtSamples include file including the new CmdRoomNeighbours command.

I hope you find this useful and thank Erik again for raising this issue.

Open MEP Connector Warning

I presented a little utility add-in yesterday that determines the maximal flow in HVAC duct connectors and populates a shared parameter with the result.

It received positive feedback, and triggered an additional request for new functionality:

Response: Looks great! This is a huge step forward. The routine runs as expected, and actually uncovered a disconnect in my sample model. I was also then able to run it successfully on other, bigger models with no issues.

One situation where we may improve the functionality might be where duct has an open end. Here are two examples of this:

In these scenarios, flow calculations are incorrect because the duct is open. In the other instances you will see an endcap in this position. It is best practice in Revit (and life) to close these systems.

Answer: Thank you for testing and confirming that it does the job.

Regarding the loose connectors, I actually implemented a quite serious application for checking those a while back, mainly as one of the early samples demonstrating use of the Idling event in Revit 2011 and 2012:

• Modeless loose connectors
• Modeless loose connector navigator update
• Yet another modeless update

The modeless loose connector navigator is a complete tool in its own right, though, enabling you to navigate through a modeless list of all unconnected connecters and manipulate the model at the same time, jumping back and forth as you like.

I have not updated it for 2014, though, and actually not even for 2013 :-)

So putting some minimal functionality into the new sample to check for open connectors instead makes good sense.

Each Connector instance provides a property IsConnected that can be used to check whether it is open or not.

It is therefore very easy to use LINQ to determine the number of open connectors, i.e. whose IsConnected property returns false, e.g. like this:

  ConnectorSet connectors
    = GetConnectorManager( e ).Connectors;
 
  int nUnconnected = connectors
    .Cast<Connector>()
    .Count<Connector>( c => !c.IsConnected );
 
  bool hasOpenConnectors = 0 < nUnconnected;
 
  string s = 0 == nUnconnected
    ? string.Empty
    : string.Format( " with {0} open connector{1}",
      nUnconnected, Util.PluralSuffix( nUnconnected ) );

I added that code to the SetMaxFlowOnElement method that I presented yesterday, and added some support for reporting back if any open connectors at all are found in the model.

This leads to an additional clause in the result message displayed at the end stating how many elements have open connectors:

The additional clause is omitted if the number is zero, as it normally should be.

The detailed information on the offending elements is provided by the log in the Visual Studio debug output console window (copy and paste to an editor or view source to see the truncated lines in full):

Duct <630420 Mitered Elbows> has 2 connectors and max flow 22.08.
. . .
Duct <630695 Short Radius> has 2 connectors and max flow 4.58.
Duct <630991 Mitered Elbows> has 2 connectors and max flow 0.
Duct <630992 Mitered Elbows> has 2 connectors and max flow 0 with 1 open connector.
Duct <630995 Mitered Elbows> has 2 connectors and max flow 4.58.
. . .
Duct <631007 Short Radius> has 2 connectors and max flow 4.58.
Duct <631074 Mitered Elbows> has 2 connectors and max flow 0.
Duct <631075 Mitered Elbows> has 6 connectors and max flow 8.33 with 1 open connector.
Duct <631077 Mitered Elbows> has 2 connectors and max flow 4.58.
. . .
Duct <632298 Mitered Elbows> has 2 connectors and max flow 8.33.

Set MEP Duct Flow Parameter:
  Set max flow parameter on 43 ducts,
  2 of which have open connectors.

Here is FlowParam03.zip containing the complete source code with the updated method implementations using LINQ as described above, the Visual Studio solution and the add-in manifest for this add-in.

Autodesk University Class Catalog Preview

The AU 2013 class catalog preview (2.5 Mb xls) listing the classes available at Autodesk University in Las Vegas in December is now available for download.

I verified that mine are all present and intact:

• DV1736 – Cloud-Based, Real-Time, Round-Trip, 2D Revit Model Editing on Any Mobile Device – This presentation demonstrates real-time, round-trip editing of a simplified 2D rendering of an Autodesk Revit intelligent model on any mobile device with no need to install any additional software whatsoever beyond a web browser. How can this be achieved? A Revit software add-in exports polygon renderings of room boundaries and other elements such as furniture and equipment to a cloud-based repository that is implemented using an Apache CouchDB NoSQL database. On the mobile device, the repository is queried and the data 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 intelligent model in real-time. All of the components used are completely open source, except for Revit itself. This is an advanced class for experienced programmers.
• DV1914 – Revit API Expert Roundtable: Open House on the Factory Floor – Interact with a panel of Autodesk Revit API experts from Autodesk to get answers to your questions and discuss all relevant topics of your choice. If you are writing add-ins for Revit software, then this is the perfect forum to get to know better the people who shape the APIs you work with and to explain your views, ideas, and problems directly face-to-face. Note that prior .NET programming and Revit programming experience is required and that this class is not suitable for beginners.
• DV2010 – Advanced Revit 2014 API Features and Samples – This class focuses on some of the major new Autodesk Revit 2014 API features. We look at API access to the project browser, dockable panels, copy and paste, command launching, the graphics pipeline, schedule formatting, and additions to the view API including demonstration and discussion of sample code. We also provide an overview of all the new Revit 2014 SDK samples. Note that prior .NET and Revit programming experience is required and that this class is not suitable for beginners.

Since popular classes often fill up quite quickly, you can use this spreadsheet to get started on your selections and help ensure that you can register for the classes you want when registration opens on September 12.

Songbird Dies, Long Live Nightingale

Completely unrelated to the Revit API, you may have noticed that I dabble with music now and then and was using Songbird a my main playing and tagging tool on Mac.

Well, Songbird shut down as a company in June, and I now moved on to Nightingale that is touted as its worthy successor and looking good to me so far.

I am also using VirtualDJ when I want to cross-fade nicely from one song to the next in a playlist.