The Building Coder

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.

Revit 2014 OBJ Exporter and New SDK Samples

Funnily enough, after dealing with the new Revit 2014 custom exporter framework last week, and even suggesting rewriting my Revit 2013 OBJ exporter to make use of it, a request came in for a version of the OBJ exporter for Revit 2014, so I discuss that below. I also add some more background to the list of new Revit 2014 SDK samples. Finally, to wrap up, we'll look at a surprisingly unbalanced distribution of Revit API blog page views per country.

OBJ Exporter for Revit 2014

As mentioned, it would be nice to rewrite my OBJ exporter for Revit 2013 using the new Revit 2014 custom exporter framework.

However, a request already came in for a Revit 2014 version:

Question: Until now I have been using Lumion for visualisation. It is fast and the result is OK. However, I now discovered the Octane renderer and would like to try that as a visualisation tool instead. Apparently, the only way to export a Revit model to Octane is via the OBJ file format.

Answer: In order to provide something immediately, I simply flat ported the Revit 2013 OBJ exporter to Revit 2014. I also made use of the DisableMismatchWarning utility to fix the processor architecture mismatch warning MSB3270.

The current implementation thus still traverses all the Revit model elements one by one, retrieves their solids, exports the graphics face by face, and determines some, but not all, graphical attributes as described last year:

• OBJ model export considerations
• Take one
• Colours
• Multiple solid support
• Transparency support

Some of that complexity could be removed by rewriting this using the Revit 2014 custom exporter API. Above all, the graphical properties could easily be better supported.

Running the OBJ exporter on the RAC basic sample model generated these OBJ and MTL output files and reported the following result:

Here is a sample visualisation in Octane of a Revit 2014 model exported to OBJ:

As you can see, the texture mapping is rather strange. Maybe the MTL file is not being properly processed.

Probably some face normals are also wrong, or, equivalently, the polygon loop vertex ordering is inverted.

Anyway, here is ObjExport2014.zip containing the complete flat ported source code, Visual Studio solution and add-in manifest for the Revit 2014 OBJ exporter.

Revit 2014 SDK Samples

I already presented the list of new Revit SDK samples without going into much detail.

I fleshed it out a bit more for the Revit API DevCamp in Moscow, as part of my presentation on the Revit 2014 API news.

The shortest useful summary of the main new API features that I have been able to achieve is this:

• Copy and paste API – within or between documents, incl. view specific elements
• Project browser API – commands, macros, selected elements
• Schedule API – formatting, read-write data items
• Command API – launch macro, add-in and built-in
• Displaced elements API – exploded views
• Join geometry API – create, remove and control joins
• FreeForm element API – modification of imported solids
• Site API – editing of topography surface points and sub-regions
• Add-in API – loading and execution
• Macro API – list, create, delete and execute
• MEP calculations in external services
• Structural Analysis SDK
• Direct API access to rendering pipeline

The three last items are the only ones not covered by any new SDK samples.

For that reason, I recently went to some effort to explore the Structural Analysis SDK and the custom exporter framework.

The third item not covered yet concerns the MEP calculations in external services. We are working on a good sample for that, hopefully coming soon.

All other important new features are covered by the following SDK samples:

• DisplacementElementAnimation
• DockableDialogs
• DuplicateViews
• ExtensibleStorageUtility
• FreeFormElement
• PostCommandWorkflow
• ScheduleAutomaticFormatter
• ScheduleToHTML
• SinePlotter
• Site
• Units
• WinderStairs

Several of these have already been discussed in the DevDays online presentation, recording and sample code and other separate posts.

Here is my Moscow DevCamp Revit 2014 API slide deck that includes one slide for each sample to provide a quick first impression of each.

Let's close for today with something not directly API related:

BIM Boosting Booms Much More in Four Specific Countries

Cheers to Australia, Denmark, Netherlands and Sweden!

When I visited Harry Mattison in Boston in connection with the Autodesk Tech Summit, he mentioned that his Boost your BIM page views had an extremely unbalanced distribution for different countries, and very kindly provided some numbers correlated with the total country population:

As you can see, the top four countries have 4, 5 and even up to almost 7 page views per 100000 population, whereas Canada has 2.5, the USA and UK well under 2, and the rest of the world well under 1.

Rather strange, isn't it?

Thank you, Harry, for this perplexing little item.

Revit Add-in Unit Testing

Here is a topic I have been flirting with for years, and never really got into seriously yet, except point to the efforts for unit testing in Revit 2011 by Rod Howarth and Daren Thomas back in 2010.

Finally, the cavalry is galloping in to our rescue in the shape of Steven Downing, Ali Talebi and Yamin Tengono of Arup.

They implemented a very complete and advanced unit testing system for Revit add-ins enabling NUnit as well as other test helpers like Moq to be used and including support for real-time addition of new tests, recompilation and reloading of add-ins, and re-running updated code and tests without restarting Revit.

The entire RvtUnit project including a sample project demonstrating its use is hosted on GitHub.

It includes a getting started document and a demonstration video showing the steps I just described:

• Launching the TestRunner external command
• Selecting a directory containing .NET assemblies defining tests to run
• The assembly DLL is loaded via a byte-code stream, so the actual file is not locked
• The tests to run are dynamically detected using custom attributes and .NET reflection
• Running the tests and reporting the unit test run results
• Switching to Visual Studio, adding a new test, recompiling
• Dynamically reloading, reparsing and retesting without leaving or restarting Revit
• Switching to Visual Studio again and adding a detailed test failure message, recompiling
• Reloading and retesting once again with the new message displayed

I would suggest looking at the 2.5 minute demonstration video right away, first thing, to see the system in action and understand exactly what can be achieved and how:

Here is the detailed content of 'Getting Started.docx':

• Introduction
• RvtUnit project
• SampleTool project

Introduction

RvtUnit is an example of how to achieve Unit Testing within Revit. By running the NUnit runner inside Revit, we can unit test code which relies on the Revit API, without having to wrap the entire Revit API.

The solution contains three projects:

• The RvtUnit project is the main project that runs the unit tests.
• The SampleTool project shows an example of a Revit IExternalCommand that includes unit tests.
• The Helpers project contains some code used by both the other projects. Notably, the RvtUnit project will store a reference to the ActiveUIDocument here, so the unit tests can pick it up.

RvtUnit Project

• Designed using the MVVM pattern.
• References a custom build of NUnit which has been modified to load DLL's from a byte array, rather than from disk
• Allows user to select a directory of DLL's, and it will then load them and present a dialog which lets the user run some or all tests.
• Contains an 'AssemblyResolve' event handler, so that any dependencies of the DLL to be tested can also be loaded. Since the assembly to be tested is loaded dynamically from a byte-array, the normal .NET Framework mechanism will not work.
• The Test runner will not execute the IExternalCommand of any DLL's. It will simply load the DLL, look for any unit tests in the DLL and then run them.

SampleTool Project

• Contains an example of an IExternalCommand that includes some classes which are unit tested.
• The 'production code' and the 'test code' are compiled into the same DLL when the project is compiled in 'Debug' mode.
• The test code is omitted when the project is compiled in 'Release' mode. This is achieved by putting test code and references inside an ItemGroup that only compiles for Debug:

<ItemGroup Condition="'$(Configuration)|$(Platform)' == 'Debug|AnyCPU'">
  <Reference Include="Moq">
    <HintPath>..\rvtUnit\Lib\Moq.dll</HintPath>
  </Reference>

  . . .

  <Compile Include="Tests\UnitTests\HasParameter_Tests.cs" />
  <None Include="Tests\Features\SetParameter.feature">
    <Generator>SpecFlowSingleFileGenerator</Generator>
    <LastGenOutput>SetParameter.feature.cs</LastGenOutput>
  </None>
</ItemGroup>

• Contains standard unit tests, and Specflow tests.
• The Specflow test also use Moq, although a custom build of both Moq and Castle.Core are required, as the objects must be properly disposed at the end of the test.
• If you run the SampleTool from the Addins menu, it will be loaded from disk and the file locked as per normal. You will then be unable to change, rebuild and reload it.

Conclusion

Jeremy adds: Wow. I have nothing left to add. Almost.

The RvtUnit sample demonstrates a number of other important and exciting other features as well, such as support for multiple versions of Revit, ranging all the way from 2010 through 2014, so a thorough exploration of the source code provided is highly recommended.

To run and test this, you need to start up Revit properly, stand-alone, not in the debugger from within the Visual Studio IDE.

A huge thank-you to Steven, Ali and Yamin for this truly impressive framework!

Recursively Disable Architecture Mismatch Warning

I recently explained the cause and resolution of the processor architecture mismatch warning MSB3270.

On closer consideration, I decided to fix it for all the ADN training material labs and samples, and actually for the entire collection of Revit SDK samples as well.

This is obviously not something you want to do manually, considering that it involves a modification of hundreds of project files.

Here are the steps involved in automating and testing this process:

• Disable mismatch warning utility
• Project file header and property group
• Property group string constants
• File processing and prerequisites check
• Recursive directory traversal
• Mainline
• Potential enhancements
• Results on SDK and ADN sample code
• Other warnings, hitherto hidden
• Download and updated ADN training material
• Update for Gopi

Disable Mismatch Warning Utility

Since this involves hundreds of project files, I implemented a script to fulfil the task. Normally, I would use either Python or a Unix shell script driving sed. In order to share it more easily with you guys and the development team, I decided to implement a C# .NET command line executable instead, DisableMismatchWarning.exe.

It recursively searches for all C# and VB project files in and below the current working directory and adds the relevant property group to them.

Project File Header and Property Group

What property group? And how, exactly, please?

Well, for instance, looking at the AddSpaceAndZone SDK sample, one of the first, alphabetically speaking, here are the first five lines in the project file with the filename extension CSPROJ (view source or copy to an editor to see the truncated lines in full):

<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
    <ProductVersion>9.0.30729</ProductVersion>

As explained in the above-mentioned discussion, I can define the required new property group to suppress the undesired compilation warning message by adding the following lines (or single long line, if desired) before the existing property groups:

<PropertyGroup>
  <ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch>
    None
  </ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch>
</PropertyGroup>

Property Group String Constants

Here are the two string constants that I define to check for an existing tag in order to tell whether a given project file has already been processed, and the entire property group to add if that is not the case:

const string _arch_mismatch_tag
  = "<ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch>";
 
const string _property_group
  = "  <PropertyGroup>\r\n"
  + "    <ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch>\r\n"
  + "      None\r\n"
  + "    </ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch>\r\n"
  + "  </PropertyGroup>\r\n";

File Processing and Prerequisites Check

Before I make this modification to a file, I obviously want to be absolutely sure that:

• I have write access to it.
• It really is a valid Visual Studio project file.
• It has not already been processed, i.e. it does not already contain a ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch tag.
• A backup file is created before adding the property group.

Here is a C# .NET method that performs these steps on a given filename, adds the new property group lines to it, and reports the results on the command line:

/// <summary>
/// Examine the given file.
/// Check that it is not read-only.
/// Check that it appears to be a valid 
/// Visual Studio project file.
/// Check that it does not already contain a 
/// ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch 
/// tag.
/// If so, create a backup file and 
/// add the property group.
/// </summary>
static bool AddPropertyGroup( string filename )
{
  bool rc = false;
 
  Console.WriteLine( filename + " -- examine..." );
 
  FileAttributes atts = File.GetAttributes(
    filename );
 
  bool isReadOnly = (FileAttributes.ReadOnly
    == (atts & FileAttributes.ReadOnly));
 
  if( isReadOnly )
  {
    Console.WriteLine( filename + " -- read-only." );
    return rc;
  }
 
  List<string> lines = new List<string>(
    File.ReadLines( filename ) );
 
  bool isProjectFile
    = lines[0].StartsWith( "<?xml version=" )
    && lines[1].StartsWith( "<Project " )
    && lines[2].Equals( "  <PropertyGroup>" );
 
  int n = 2;
 
  if( !isProjectFile )
  {
    isProjectFile
      = lines[0].StartsWith( "<Project " )
      && lines[1].Equals( "  <PropertyGroup>" );
 
    n = 1;
  }
 
  if( !isProjectFile )
  {
    Console.WriteLine( filename + " -- not a Visual Studio project." );
    return rc;
  }
 
  bool hasArchMismatchTag = 0 < lines.Where(
    a => a.Contains( _arch_mismatch_tag ) ).Count();
 
  if( hasArchMismatchTag )
  {
    Console.WriteLine( filename + " -- already has an architecture mismatch tag." );
    return rc;
  }
 
  Console.WriteLine( filename + " -- process..." );
 
  File.Copy( filename, filename + ".bak", true );
 
  lines.Insert( n, _property_group );
 
  File.WriteAllLines( filename, lines );
 
  rc = true;
 
  return rc;
}

Recursive Directory Traversal

I would like to apply this method recursively to all files with a CSPROJ or VBPROJ filename extension.

I looked and quickly found the following suggestion for a recursive file search in .NET as a starting point:

/// <summary>
/// Return full path of all files mathing pattern
/// found recursively below the given root folder.
/// </summary>
/// <param name="root">Root starting folder</param>
/// <param name="searchPattern">Filename pattern</param>
/// <returns>Enumeration of full file paths</returns>
static IEnumerable<string> Search(
  string root,
  string searchPattern )
{
  Queue<string> dirs = new Queue<string>();
 
  dirs.Enqueue( root );
 
  while( 0 < dirs.Count )
  {
    string dir = dirs.Dequeue();
 
    // files
 
    string[] paths = null;
 
    try
    {
      paths = Directory.GetFiles(
        dir, searchPattern );
    }
    catch
    {
      // swallow
    }
 
    if( paths != null && 0 < paths.Length )
    {
      foreach( string file in paths )
      {
        yield return file;
      }
    }
 
    // sub-directories
 
    paths = null;
    try
    {
      paths = Directory.GetDirectories( dir );
    }
    catch
    {
      // swallow
    }
 
    if( paths != null && paths.Length > 0 )
    {
      foreach( string subDir in paths )
      {
        dirs.Enqueue( subDir );
      }
    }
  }
}

As explained by its author, it avoids the access denied exception thrown by the built-in recursive search and is lazily evaluated, returning results as soon as it finds them.

Mainline

With these two methods in place, there is nothing left for the console application mainline to do, beyond determining the current working directory and launching the process:

/// <summary>
/// Add a new property group to suppress the 
/// processor architecture mismatch warning MSB3270
/// to all Visual Studio C# and VB .NET project 
/// files with the filename extension CSPROJ or 
/// VBPROJ found recursively in the current working 
/// directory or any of its subfolders.
/// </summary>
static int Main( string[] args )
{
  string root = Directory.GetCurrentDirectory();
 
  foreach( string match in Search( root, "*proj" ) )
  {
    string path = match.ToLower();
    if( path.EndsWith( ".csproj" )
      || path.EndsWith( ".vbproj" ) )
    {
      AddPropertyGroup( match );
    }
  }
  return 0;
}

Potential Enhancements

It might be cleaner to handle this by reading and writing the project files as XML files, not just simple line-based text.

This utility will not overwrite a read-only file. The standard Revit SDK installation sets all project files to read-only, so you may have to change that before you can run the utility.

Results on SDK and ADN Sample Code

Initially, it processed only 56 project files out of the total 169 provided in the Revit 2014 SDK. Others were not recognised as valid Visual Studio projects.

For instance, some (or all?) VB project files apparently lack the initial ?xml tag line, and the first attribute of the Project tag may be either DefaultTargets or ToolsVersion.

The criteria I initially applied to check for a valid Visual Studio project file were stricter than the ones listed above. Relaxing them slightly enabled the utility to successfully recognise and process all 169 Revit SDK projects.

All of those pesky architecture mismatch warnings are now eliminated.

Other Warnings, Hitherto Hidden

Once the hundreds of architecture mismatch warnings were gone, I noticed five completely unexpected and unrelated new warning messages that previously were impossible to find in the multitude:

1. XML comment is not placed on a valid language element C:\a\lib\revit\2014\SDK\Samples\FamilyCreation\WindowWizard\CS\Command.cs 41 9 WindowWizard
2. ExternalCommandRegistration: Could not locate the assembly "RevitAddInUtility". Check to make sure the assembly exists on disk. If this reference is required by your code, you may get compilation errors.
3. The referenced component 'RevitAddInUtility' could not be found.
4. RoutingPreferenceTools: Could not locate the assembly "RevitAPIIFC". Check to make sure the assembly exists on disk. If this reference is required by your code, you may get compilation errors.
5. The referenced component 'RevitAPIIFC' could not be found.

All five were trivial to fix manually by removing the offending elements, i.e. an erroneous comment in the WindowWizard Command.cs and the two completely unnecessary RevitAddInUtility and RevitAPIIFC assembly references in the ExternalCommandRegistration and RoutingPreferenceTools projects.

Download and Updated ADN Training Material

You can download the complete source code and Visual Studio solution from my DisableMismatchWarning GitHub repository, my second foray into this realm.

I also updated all the ADN training material labs and sample applications.

The last version I posted was set up to refer to the Revit Architecture 2014 API assemblies.

I now switched to Revit 2014 Onebox, to I changed the path to these from C:\Program Files\Autodesk\Revit Architecture 2014 to C:\Program Files\Autodesk\Revit 2014.

The compilation of the last version of the ADN Revit API training labs that I posted still generated 35 warnings. The new version reduces these to 19 warnings.

Here is adn_src_2014_1.zip including the updated source code, lab instructions, Visual Studio solutions and add-in manifests of the ADN Revit API training labs, Revit MEP sample, and Revit Structure labs, link and other samples, which was last published in three separate chunks:

• ADN Training Labs for Revit 2014
• ADN AdnRme sample for Revit MEP 2014
• ADN Training Material for Revit Structure 2014

Update for Gopi

After comparing my ADN sample code with my colleague Gopi's version, I discovered that he had corrected one deprecated API usage warning that I had not.

In order to get us better synchronised, I went ahead and fixed that, only to discover that once I started, I might as well go ahead and fix a few more.

Here is therefore an updated version 2014.0.0.2 of the ADN Training Labs for Revit 2014, whose compilation now only produces 7 warnings.

It also includes Gopi's updated version of the lab instruction documents.

I would have said that 'we'll get there eventually', meaning 'down to zero warnings', only a few of these are actually intentional, for demonstration purposes...

Behind the Scenes of the NBS Revit Add-in

Here is a guest post by Stephen Hamil of RIBA Enterprises, director of NBS, the national standard specification company in the UK, owned by the Royal Institute of British Architects.

They just released the new version of their Revit plug-in that integrates the Revit design model with the NBS specification model, technical guidance and National BIM Library objects.

Below, Chris and Calum from the NBS software development team give a little insight into some of the API functionality they used when developing this software:

• Drag-and-drop support from the National BIM Library
• Controlling Revit from modeless dialogues
• Porting to 2014
• Docking panel prototype
• Further Information

Drag-and-drop Support from the National BIM Library

We make use of the IDropHandler interface from the API to allow us to drag drop from the National BIM Library NBL.

That enables us to overwrite the default behaviour of Revit when the user drops a family on a project file.

We start the process by making a call from the web browser to its owning user control:

  /// <summary>
  /// Method called from the web browser
  /// </summary>
  public override void ClickDrag(
    string downloadLink,
    string strFamilyName )
  {
    if( this.nbsUser.hasLoggedInNBL )
    {
      List<string> dragInfo = new List<string>() {
        downloadLink, strFamilyName };
 
      // Kick off the drag drop event which Revit 
      // will pick up and custom code will check 
      // if family already entered
 
      UIApplication.DoDragDrop( dragInfo,
        new dropHandler( this ) );
    }
    else
    {
      this.SignInToFloatPanel();
    }
  }

Controlling Revit from Modeless Dialogues

We use the Idling event to call into the Revit API from modeless dialogs to modify the database without causing damage.

We have a list of commands to run with an array of objects as their parameters and then run this chunk of code to process them in the Idling event handler:

  // If we have commands to process
 
  if( CommandsToProcess.Count > 0 )
  {
    try
    {
      UIDocument uiDoc = UIApp.ActiveUIDocument;
 
      // Get the first command in the list to process
 
      CommandToRun command = CommandsToProcess.First();
 
      // Get the delegate that we want to run
 
      Delegate FunctionDelegate = command.FunctionToRun;
 
      // Make sure we have the lastest UIDocument
 
      command.ListOfParameters.Insert( 0, uiDoc );
 
      // Get it's parameters
 
      object[] Parameters = command.ListOfParameters.ToArray();
 
      // Invoke our function
 
      FunctionDelegate.DynamicInvoke( Parameters );
    }
    catch( Exception ex )
    {
      ErrorLogger.LogError( "Error processing command: "
        + ex.ToString() );
    }
    finally
    {
      // Always Pop the first in the queue
 
      CommandsToProcess.RemoveAt( 0 );
    }
  }

Porting to 2014

We encountered a problem when developing the plugin to work with 2014, due to the Document class method get_Element changing to GetElement.

This was easily handled by the way we structure the plugin and have each version inheriting from the previous; we start off with a generic interface:

  public class RevitRibbon : IRevitRibbon

For Revit 2013 and 2014, we inherit the previous RevitRibbon class:

  public class RevitRibbon : Revit2012.RevitRibbon

  public class RevitRibbon : Revit2013.RevitRibbon

This allows us to simply override the one function calling the get_Element method, solving the problem without causing any damage to our existing implementations for Revit 2012 and 2013.

Docking Panel Prototype

For the Revit 2014 users, we did also look into replacing the modeless dialog by a docking panel, which is a really cool new feature.

Unfortunately, though, we ran out of time for this release. However, we’ll look at this again for version 2.1.

Here is a screen snapshot of it working in a prototype:

Further Information

A lot of work was put into this and it looks pretty good, really linking the design model in Revit with the specification model in NBS.

Here is some further information on:

• The main seven features of the new NBS plug-in.
• The UK free-to-use library of NBS BIM components.

Thank you, Stephen, for providing this background information.

Sun Direction, Shadow Calculation and Wizard Update

I enjoyed some wonderful hot sunny days since I returned from New England back to Switzerland.

Summer finally arrived. A nice change after the rain and cold both here and in New Hampshire and Massachusetts.

Talking about rain and sun leads up nicely to today's topic, on the sun direction and shadow calculation in a Revit BIM.

Before I get to that, though, I present an update of my Revit add-in wizards resulting in part from yesterday's post on the processor architecture mismatch warning:

• Visual Studio Revit add-in wizard update
• Calculating and marking shaded areas
• Determining sun direction

Visual Studio Revit Add-in Wizard Update

I implemented updates of my Visual Studio wizards to generate new C# and VB Revit 2014 add-ins yesterday, for two reasons:

• Suppress the processor architecture mismatch warning by adding a property group to the Visual Studio project file – I always try to compile all my projects with zero warnings.
• Modified the Revit executable and API assembly paths to refer to Revit Onebox instead of the architectural flavour – the former was unavailable when I first installed Revit 2014.

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

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

For all further details on this, links back to previous versions, other flavours, and tips on how to adapt the wizards for your own use, please refer to the initial 2014 version.

Calculating and Marking Shaded Areas

Determining the shaded areas in a model is obviously important for many areas of analysis.

Assuming certain objects in the BIM cast a shade over others, is there a way to programmatically determine the shadowed areas?

In fact, the Revit API provides a dedicated ExtrusionAnalyzer class for this very kind of calculation, which I made use of to determine the plan view furniture and equipment boundary loops for my 2D cloud-based editor workflow.

Is there a way to mark these areas in the model?

That sounds rather complicated. You might be able to use Boolean operations for 2D polygons and paint the shaded areas.

Calculating Sun Direction for Shadow Calculation

This leads to the following

Question: I found code snippet showing how to use the ExtrusionAnalyzer class to calculate shadows in the material provided for the Autodesk University class on Geometric Progression: Further Analysis of Geometry using Autodesk Revit 2012 API.

To make use of it, I also need to determine the sun direction using the Revit API. It obviously differs based on time of the day, location, etc.

How can I obtain the sun direction for any given project location, date and time, please?

Answer: The sun direction is available from the Sun and Shadows element. Of course, it always represents a single point in time (date, time) and not the complete range of possible sun directions. The sample takes this into account and recalculates shadows when the sun is moved to another date and time location via the user interface.

Here is the code to determine the sun direction from the sun and shadows settings:

public class ShadowCalculatorUtils
{
  public static XYZ GetSunDirection( View view )
  {
    SunAndShadowSettings sunSettings 
      = view.SunAndShadowSettings;
 
    XYZ initialDirection = XYZ.BasisY;
 
    //double altitude = sunSettings.Altitude;
 
    double altitude = sunSettings.GetFrameAltitude( 
      sunSettings.ActiveFrame );
 
    Transform altitudeRotation = Transform
      .CreateRotation( XYZ.BasisX, altitude );
 
    XYZ altitudeDirection = altitudeRotation
      .OfVector( initialDirection );
 
    //double azimuth = sunSettings.Azimuth;
 
    double azimuth = sunSettings.GetFrameAzimuth( 
      sunSettings.ActiveFrame );
 
    double actualAzimuth = 2 * Math.PI - azimuth;
 
    Transform azimuthRotation = Transform
      .CreateRotation( XYZ.BasisZ, actualAzimuth );
 
    XYZ sunDirection = azimuthRotation.OfVector( 
      altitudeDirection );
 
    return sunDirection;
  }
}

Structural Analytical Code Checking and Results Builder

In case you have not noticed, I would like to point out one important specialised addition to the Revit 2014 SDK: the new Structural Analysis Software Developer Kit.

It lives in its own sub-directory Structural Analysis SDK and consists of documentation, sample code and Visual Studio templates for two main components:

• Code checking framework
• Facilitate code checking workflows
• For both users and developers
• Complete extensible add-in
• User interface, report generator, data storage
• Documentation, samples, Visual Studio templates
• Results builder framework
• Store and access results data in Revit
• High-level API for consumption, exchange, remote providers

Here is an overview of the sample applications provided with this toolkit:

• ExtensibleStorageUI and ExtensibleStorageDocumentation – exercise the ExtensibleStorage framework user interface and reporting functionality.
• CodeCheckingConcreteExample – a concrete code checking application with step-by-step document.
• ConcreteCalculationsExample – concrete calculations component for all cases listed in the calculation manual.
• SectionPropertiesExplorer – demonstrate use the engineering component.
• StoringResults and QueryingResults – store and query structural analysis results stored in BIM using the results builder component.

If you are active in this area, this provides a big lump of functionality you definitely need to be aware of, similarly to the REX SDK and content generator.

In a related vein, here is a question that just arose today:

Question: I would like to start working programmatically with Autodesk Robot to read relevant data result from structural elements such as beam, column, foundations, slab etc.

Where can I find some information about that, please?

Answer: Please take a look at the discussion of the Robot Structural Analysis API.

Good luck!

Addendum: Here is the complete Robot API documentation and tutorial from April 2010, copied from the API Tutorial thread on the Autodesk Robot Structural Analysis discussion group. Note that this information is pretty dated by now, so I would not recommend putting in any significant effort developing new projects based on this today.

Tech Summit and More AutoExport Considerations

Today is the day I have been working towards with my cloud-based round-trip 2D Revit model editing project, which I am presenting this afternoon (cf. the 30-minute pre-recorded video).

Before I get to that, I would like to pass on the following thoughts and suggestions on yesterday's auto PDF batch printing system from Constantin Gherasim of Genivar Inc. on a similar project of his own, up in use and running for over a year already, expanding on what he already said in his comment yesterday:

Thoughts on the Genivar AutoExport System

As I mentioned, this is another Revit "AutoExport" utility, using a similar approach as Dan's: an overnight batch exporter based on the Windows task scheduler and the Revit Idling event.

I would like to share some information on the similarities and differences in the hope that it be useful for others as well.

In order to see what the interface looks like, here is a screen snapshot of it showing the list of files to export:

Here is the tab handling the DWF format export settings:

The utility uses a configuration file, which is stored in XML format:

It is controlled through a couple of registry keys which are preconfigured for the task by an AutoIT script:

The first registry key specifies the XML configuration file path. The second one is a pseudo Boolean flag (in fact it's a string), which controls whether the utility is run or not at the Revit startup (this is necessary when using Revit out of this setup).

The exported formats are PDF, DWG, DXF, DWF and DGN. As a new extension project, I would like to add support for the IFC format.

The way it works is pretty similar with the tool presented by Mr Tartaglia. Here is a detailed explanation:

The setup:

1) A scheduled task on a server starts a dedicated remote session each midnight, by logging on a specific account on a specific machine on the network (ideally on the LAN), machine which is dedicated to this task, therefore it's "On" all the time and has all the resources available for the task.

2) When the logon process is completed, a main AutoIT script placed in the StartUp folder of the logged account, triggers successively two other auxiliary AutoIT scripts. The reason for the two other scripts is the fact that two distinct exporting processes are required for two different teams, each with its own configuration file (obviously the setup can be extended, there could be a third and a fourth session, and so on, depending on how long it takes for one process and knowing that the time we have it’s eventually between midnight and 7:00 AM).

3) The first auxiliary script writes to the registry the path for a specific configuration file (which is maintained somewhere on the network), writes "True" to a specific key in the registry named "RunOnStartup", and then it starts Revit (with a dummy document for Revit 2012).

4) When the Revit Idling event is fired, the AutoExport utility first checks the registry and if the key "RunOnStartup" is "True", it opens the configuration file from the specified path and starts exporting the documents listed in the configuration file to the target folder, specified in the same configuration file (along the export process, it writes a log file).

5) Meanwhile, the first auxiliary script is waiting for the same "RunOnStartup" registry value to be switched to "False" by the AutoExport application, which happens as soon as all the documents listed in the configuration file are processed. As soon as the last exported document is closed, the AutoExport application changes the value for "RunOnStartup" to "False", then the first auxiliary script kills the Revit process by its PID, sends an email (with the last log file attached) to me and to the person which maintains the configuration file, and it stops.

It's important to mention the fact that leaving the value of "RunOnStartup" key to "False" is the mechanism that ensures that the AutoExport application won't run out of this setup.

6) After a brief delay, the main script triggers the second auxiliary script, which writes to the registry its own values and the whole process (steps 3 to 5) restarts, only with a different configuration file and a different export folder.

7) After the second auxiliary script is over and the Revit process is killed again, the main script closes the remote session on the dedicated machine, which is now waiting for the next AutoExport session in next 24 hours.

This setup has been in place for more than a year now, and basically works without a glitch. As you can see in the email screen snapshot, it can process up to 25-30 Revit files in one session, which takes about 30 to 40 minutes.

I was quite surprised by the similarity of this project with the one described yesterday, although similar requirements do generally lead to similar solutions.

Then I thought that the approach with the auxiliary scripts through the registry offers a little bit more flexibility and control.

My approach is a little bit more optimistic, since I process multiple RVT files per Task Scheduler Task.

I would also like to mention that maintaining a log file seems to me a good thing to do, which together with the automated email is a nice bonus in my opinion.

These both confer some kind of peace of mind, when you know that you don’t have to wait for somebody to complain that there were problems, since it’s possible to check the night’s job on the mobile phone in the early morning and alert the concerned people!

Of course, these are more or less cosmetic improvements, but when put together, it all seems to me a handy and solid tool.

For me it’s enough that it works and my folks are happy :-)

Unfortunately this is an in-house application only, so I cannot share it as openly as Mr Tartaglia very graciously did.

I hope these ideas are of use, not necessarily as an improvement, because it depends, to anyone with similar needs and the necessary skills.

I hope I was clear in my explanations and also that you will find this useful.

Thanks for your interest and time.

Thank you, Constantin, for sharing these additional thoughts.

Rod's Revit Remote Boot

In another comment on yesterday's post, Barry Ralphs of Tipping Mar pointed out an interesting neat and generic use of the Idling event by Rod Howarth: Revit remote boot – a technique to run an API add-in on a particular Revit model without user interaction.

Other Important Posts on this Topic

If you are interested in this kind of automation, you should not miss the old posts on a pattern for semi-asynchronous Idling API access and driving Revit through a WCF service.

Ok, I hope I have not missed anything important now. Wish me luck for this afternoon!