The Building Coder

Autodesk View and Data API

I was away for a few days last week in the beautiful Italian speaking southern part of Switzerland.

Back again, as usual, I am confronted with a host of Revit API issues.

The most important event last week for me by far, though, was the release of the Autodesk View and Data API.

Some of my Autodesk University related tasks and upcoming meetup events are also related to that:

• Autodesk View and Data API
• View and Data API presentations
• Autodesk University advance passes
• Retrieving support information for an element
• Inserting a family symbol from a type catalogue
• API access to revision information
• Installing a Revit add-in

Autodesk View and Data API

As said, Autodesk released its new web based View and Data API.

I will not go into any details, because full documentation and samples are provided:

Full API documentation and access to request an API key is provided by the Autodesk Developer Portal.

Support is available through the Autodesk Community > Web Services API > View and Data API discussion group.

Samples are provided in the GitHub View and Data API sample repositories.

The best way to get started is by hitting the appropriately named 'Get Started' button on developer.autodesk.com and working through the seven simple steps in the Quick Start document:

1. Register for an API key and create an application
2. Get your access token
3. Create a bucket
4. Upload a file
5. Set up References Between Multiple Files
6. Register Your Data with the Viewing Services
7. Load the URN in the JavaScript viewer

Oops.

I said 'released'. Reading Stephen Preston's welcome message to the forum, I note that "we expect the API to become 'public' very soon". If you'd like to be informed when that happens, then please reply to the Tell me when this API is public thread, making sure to include your name, company and contact details. API keys are currently only provided to pilot program participants.

View and Data API Presentation at Basel.js Meetup and Autodesk University

I'll discuss and demonstrate the new View and Data API at the next Basel.js meetup with the title New 3D Geometry Viewer for Web:

"You may have created fantastic 3D designs. Isn't it frustrating that your website is all in 2D? Now you can very easily embed stunning, interactive, intelligent 3D models into your web page, web application, or desktop application. We'll look at some demos showing what is possible, and cover the simple steps to create a 3D-enabled website."

Stephen Preston is presenting on this topic at Autodesk University 2014 in Las Vegas, and I will do the same at the German-speaking event in Darmstadt.

Autodesk University Advance Passes

By the way, AU attendees can buy Advance Passes before the normal AU registration opens. That gives you the following important benefits:

• Save $600 off full price of AU Advance Pass: $1,575, AU full price: $2,175)
• Choose classes and hotel a week before general registration opens, giving the attendee a better chance at getting into the classes and hotel he or she wants

Advance Pass holders can register starting on August 20, 2014, one week before Open Registration starts on August 27, 2014.

Retrieving Support Information for an Element

Question: I would like to know which element sits on top of the other.

For example, I have a floor element sitting on top of 10 columns. I would like to know which columns support the floor.

Alternatively, if I have 10 columns on top of a floor 'X', I would like to know how to extract the information for each column to know that a floor supports this column and the floor is 'X'.

Please let me know if this is possible in Revit.

Answer: Of course, this is definitely possible in Revit.

In a properly designed structural model, you would simply make use of the analytical model to determine this information, e.g. via the AnalyticalModel.GetAnalyticalModelSupports method.

Each AnalyticalModelSupport class instance represents one support for a structural element in the realm of the Analytical Model.

If your model is not structural or has been incompletely specified, there are a number of different approaches available to determine the neighbouring elements below a given element via ray casting or geometrical analysis.

An overview and examples of several different approaches is provided by the analysis of how to determine supporting columns.

Inserting a Family Symbol from a Type Catalogue

Question: Is there any API support for loading a family and creating a symbol from a type catalogue?

If not, I assume that I can write my own code for parsing the catalogue and create the symbol myself. Can you see a problem with that?

Answer: That sounds perfectly sensible. I see no problem with that whatsoever.

You can load a family, either entirely with all its symbols or just one specific type, using the LoadFamily and LoadFamilySymbol methods. Here are some thoughts and background information on loading selected family types.

By type catalogue, I assume you mean the text file specifying a list of possible dimension combinations?

I do not believe the Revit API provides support for that, so it might indeed be best to parse the file yourself and extract the desired dimensions from it.

You can then load one specific family symbol into the project, duplicate it using the Duplicate method, and set the desired dimensions to the required values.

API Access to Revision Information

Question: I am trying to obtain data relating to the revisions present on a ViewSheet.

I can successfully retrieve what looks like the correct information via GetAllProjectRevisionIds, but the PROJECT_REVISION_REVISION_NUM parameter contains no information, and PROJECT_REVISION_REVISION_ENUMERATION always appears to contain '0' (zero) regardless of the Numeric or Alphabetic selection in Sheet Issues/Revisions.

I used a modified version of Max' revision wrapper class for my tests.

The test sheet in question contains 4 revisions, two of which are alphabetic, and two numeric. The output when I retrieve data using the sample code is:

  Number: Numbering: 0 Description: My description 1, Date: 4/1/14 Sequence: 4
  Number: Numbering: 0 Description: My description 2, Date: 5/1/14 Sequence: 5
  Number: Numbering: 0 Description: My description 3, Date: 6/1/14 Sequence: 6
  Number: Numbering: 0 Description: My description 4, Date: 7/1/14 Sequence: 7

Should I expect to see anything in Number, or do I need to calculate this using the Numbering option and the sequence number? Should I expect to see a different value for Numbering if alpha or numeric values are chosen?

Answer: In versions prior to Revit 2015, the API provided hardly any access at all to revision data.

One of the major Revit 2015 API additions is access to revision information.

I recently implemented a sample application showing how to use this access to read revision data and display it in a dynamically generated Windows form on the fly.

Installing a Revit Add-in

The best way to understand how to install a Revit add-in is to read the Revit API getting started material.

However, this material is targeted at developers.

I wrote a shorter and simpler answer addressing the minimal basics answering a comment by Frédéric on the AutoPDF print utility:

All Revit add-ins are installed in the same way.

They consist of an add-in manifest with the filename extension *.addin.

It is an XML file that you can edit and contains a tag pointing to the .NET add-in assembly DLL.

The add-in manifest must be located in a folder that Revit searches, e.g. the one you mention.

The add-in assembly can be placed anywhere you like.

I place small simple add-ins in the same folder as the add-in manifest.

Then there is no need to specify the full DLL pathname.

I hope this succinct summary is useful for non-developers.

Well, I am back in the rut again now...

RevitLookup for UR1, ADN, AEC and AU News

Here are some of the non-confidential items from the new confidential April 17 Autodesk Developer News newsletter, plus one or two additional items of interest from myself and elsewhere:

• AEC Technology Symposium
• Migrate Autodesk Exchange Apps and publish 2015 versions
• Proposals for Autodesk University 2014
• Proposals for Autodesk University Germany 2014
• Autodesk ReCap Connect Partnership Program
• RevitLookup for Revit 2015 UR1
• Happy Easter!

AEC Technology Symposium

I already pointed out the upcoming AEC Technology Symposium in New York City on May 16-18.

I mentioned the bad news, the absence of our bi-annual AEC DevCamp this year, and the good news, namely our participation in this event.

The best news of all is that I will be able to participate myself, so I hope to see you in New York a month from now.

The symposium itself is held on Friday the 16th, followed by a Hackathon over the weekend.

You can learn more and register for the event at http://core.thorntontomasetti.com/aec-technology-symposium-2014.

I hope to meet many of you that attended the AEC DevCamp in the past, and also get to know many new developers interested in cutting edge AEC technology, BIM 360, Dynamo, Revit, and non-Autodesk AEC technologies too.

Migrate your Autodesk Exchange Apps and Publish 2015 Versions

Customers are actively looking for 2015 versions of their favourite add-on tools, so make sure your apps are ready and available. Don't miss out on the opportunity to be found by all the new customers moving to Autodesk's 2015 solutions.

Please direct any questions on migrating your existing apps to appsubmissions@autodesk.com.

If you are submitting new apps, review the information at www.autodesk.com/developapps.

Autodesk University 2014 Call for Proposals Coming Up

You certainly know about AU, Autodesk University, Autodesk's largest annual user conference, with hundreds of classes and labs taught by top-notch instructors and industry professionals.

If you're interested in becoming a speaker at Autodesk University this year, you can now sign up to be notified when the AU 2014 Call for Proposals opens.

Speaker benefits include enhancing your reputation and increasing your networking opportunities, as well as speaker honoraria.

For further details visit http://au.autodesk.com/speaker-resource-center/overview.

Obviously, as always, I plan to submit a couple of proposals myself.

Autodesk University Germany 2014 Call for Proposals

Besides the main Autodesk University event in Las Vegas, I am also hoping to attend the German venue in Darmstadt this year, October 23-24.

The call for proposals for Autodesk University Germany 2014 is already open, and I plan to submit some here as well.

Autodesk ReCap Connect Partnership Program

You certainly know about ReCap, the reality capture functionality producing 3D point clouds and models from a series of 2D pixel images, e.g. normal camera snapshot photos.

Autodesk now announced the ReCap Connect Partnership Program covering several different methods to programmatically connect to and make use of this service:

• Capture Codec Kit
• Embedded ReCap OEM program
• ReCap Photo Web API

RevitLookup for Revit 2015 UR1

I published RevitLookup for the Revit 2015 Meridian pre-release PR10 before the final customer release, which ended up being UR1.

The complete source code, Visual Studio solution and add-in manifest, is provided in the RevitLookup GitHub repository, and the new UR1 version is stored there as release 2015.0.0.1.

I changed nothing from the PR10 version, except updating the Revit API references, so the compilation obviously still generates the same 19 warnings as before.

Happy Easter

I am visiting my sister Helene in the Provence in southern France for a few days, enjoying spring and the Easter holiday.

Happy Easter to you too!

Lots of Clouds

Let me recapitulate my cloud related explorations for my simplified 2D BIM editor, since I will be discussing it again at a web-based BIM workshop later this week.

Before getting to that, though, talking about cloud related topics reminds me of some others of completely different nature that are near and dear to me:

Clouds in La Palma

Cloud Atlas

Cloud-based simplified BIM editor

Autodesk cloud service overview

Updated RevitLookup on GitHub

Above, in and under the Clouds of la Palma

My hiking trip on La Palma was definitely on interesting study of clouds, from close and afar, inside and out.

Happily, I was mostly above them, e.g. wandering the sunny ridge around the Caldera de Taburiente National Park, reaching its highest point at the Roque de los Muchachos, looking back over the roiling clouds and the ridge in the east that we walked along for three days, with the Mount Teide of Teneriffa in the background far behind it, 90 km distant:

From there we descended into the depths of the Caldera itself and admired the same ridge from below, assailed by clouds as ever:

We emerged from the Caldera to cross the impressive volcanoes in the Parque Natural de Cumbre Vieja in the south, again above the clouds, looking back northwards at the ever cloud-filled and overspilling Caldera:

After spending the night up on the volcanoes, we were decisively chased away by more aggressive clouds backed up by strong and cold storm winds:

Happily, we made it down to a warm and sunny beach to dry off and recuperate a bit before starting the long journey back home again.

Cloud Atlas by David Mitchell

Another highly recommended cloud related topic is the extremely impressive and wonderful book Cloud Atlas by David Mitchell, recently and almost equally impressively converted to a film by Lana Wachowski, Andrew Wachowski and Tom Tykwer. I absolutely loved them both. I found the book revolutionary. I never read anything like it. The film is revolutionary as well, and an unbelievable feat. Tykwer and the Wachowskis met for a week in isolation to hatch ideas, then visited the book author Mitchell to hear what he thought of them. It helps to read the book first, though, to understand anything at all about what is going on in there.

Cloud-based Real-time Round-trip Simplified 2D BIM Model Editor

I'm attending a cloud workshop in the next few days, so I dug out the recordings from my Autodesk Tech Summit and Autodesk University presentation DV1736 – Cloud-Based, Real-Time, Round-Trip, 2D Revit Model Editing on Any Mobile Device. Here is the class summary:

This class 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.

Here are direct download links to all the class materials:

• Handout
• Slide deck
• AU recording
• Live recording
• Preview recording
• RoomEditorApp – Revit add-in desktop component
• roomedit – CouchDB cloud database source code

I already discussed all the details of all the different components here on The Building Coder, and that just about covers what I personally have to contribute right now to cloud and mobile applications interacting directly with Revit.

Autodesk Cloud Service Overview

Obviously, Revit itself is making more and more use of cloud-based services, and the offerings provided by Autodesk are growing in all directions as well; here is a good overview website for all currently available Autodesk services: autodesk.com/360-cloud.

For a quick text-based overview, here is my list from the cloud & mobile platform web service API presentation given at AU:

• Identity
• Autodesk Single Sign-On Services
• OAuth – i
• Federated Sign-On
• Viewing
• Viewing Services
• Translation Services
• Creation
• AutoCAD 360 Services
• Fusion 360 Services
• InfraWorks Services
• ReCap Photo Services – ii
• AutoCAD Core Engine Services (ACES)
• Simulation
• Render Services
• Building Performance, Green Building Studio Services
• Collaboration (Social)
• Autodesk 360 (Pro) Services
• BIM 360 (Glue + Field) Services – ii
• PLM 360 Services
• Business
• Licensing Services
• Exchange

As always, Autodesk is interested in making APIs available for these services, just like all other products, to provide a strong platform for automation of the related tasks. I added an 'i' to the ones already providing a deep and broad API, and an 'ii' to the ones already equipped with a maturing API. The rest are still under consideration.

The existing APIs are not accessible yet, though, either, since we are still working on pilot programs to get them ready for public consumption.

Updated RevitLookup on GitHub

Finally, as you hopefully already know, RevitLookup now lives on GitHub, also up in the cloud somewhere, so to speak, accessible to all.

This vastly simplifies collaboration, and you are heartily invited to participate in improving it.

One friendly supporter is Florian Schmid of SOFiSTiK AG.

He future-proofed RevitLookup by removing compiler warnings, and significantly extended the functionality for snooping of geometry, FormatOptions and RevitLinkInstances.

Another step of future-proofing that I performed was to bump the years listed in the copyright notices from 2013 to 2014, and, for the first time, incrementing the build version number.

The current version right now is thus release 2014.0.1.0.

You should probably always go for the most up-to-date master branch when downloading.

Calculating a Rolling Offset Between Two Pipes

Here is a nice little MEP related external command that I implemented to calculate a rolling offset for pipes at the CASE BIM Hackathon at AU, prompted by a suggestion by Harry Mattison and Matthew Nelson.

It calculates the rolling offset between two selected pipes and generates a model line in the Revit model to display the result.

In brief, a rolling offset is an angled pipe segment that connects two pipes with each other.

For instance, imagine a situation with two parallel horizontal pipes, offset from each other in all three directions, X, Y and Z.

The task consists in calculating the appropriate angled segment to connect the two.

Maybe the best way to explain the task is to show the solution in action before looking at the detailed implementation.

Given the two parallel offset pipes, one needs to decide how far along the axis defined by their common direction to place the angled segment.

I decided to choose the midpoint defined by the the two pipes' endpoints that are farthest apart, and place the angled segment so that its midpoint coincides with that.

Here is a 52-second video of the rolling offset add-in recorded live in situ at the CASE BIM Hackathon:

In case you prefer stills, here are six screen snapshots highlighting the situation, three before and three after executing the command:

3D view before

East view before

North view before

3D view after

East view after

North view after

If you look carefully, you will notice that both selected pipes are shortened by the external command. A model line is drawn at a 45-degree angle to the existing pipes to connect the two correspondingly adjusted endpoints.

The algorithm supports any other angle as well, of course, e.g. 30 or 60 degrees; it is currently hard coded.

Rolling Offset Calculation Implementation

I implemented the external code calculating the rolling offset and generating a model line to represent the result as a new external command CmdRollingOffset in The Building Coder samples.

For a maximum of flexibility, comfort and efficiency in testing it, it supports three different possibilities for selecting the two pipes:

• Run in a model containing exactly two parallel offset pipe elements, they will be automatically selected.
• Pre-select two pipes before launching the command.
• Post-select them when prompted.

Here is the entire command implementation:

[Transaction( TransactionMode.Manual )]
class CmdRollingOffset : IExternalCommand
{
  const string _prompt
    = "Please run this in a model containing "
    + "exactly two parallel offset pipe elements, "
    + "and they will be "
    + "automatically selected. Alternatively, pre-"
    + "select two pipe elements before launching "
    + "this command, or post-select them when "
    + "prompted.";
 
  /// <summary>
  /// Allow selection of curve elements only.
  /// </summary>
  class PipeElementSelectionFilter : ISelectionFilter
  {
    public bool AllowElement( Element e )
    {
      return e is Pipe;
    }
 
    public bool AllowReference( Reference r, XYZ p )
    {
      return true;
    }
  }
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
 
    // Select all pipes in the entire model.
 
    List<Pipe> pipes = new List<Pipe>(
      new FilteredElementCollector( doc )
        .OfClass( typeof( Pipe ) )
        .ToElements()
        .Cast<Pipe>() );
 
    int n = pipes.Count;
 
    // If there are less than two, 
    // there is nothing we can do.
 
    if( 2 > n )
    {
      message = _prompt;
      return Result.Failed;
    }
 
    // If there are exactly two, pick those.
 
    if( 2 < n )
    {
      // Else, check for a pre-selection.
 
      pipes.Clear();
 
      Selection sel = uidoc.Selection;
 
      n = sel.Elements.Size;
 
      Debug.Print( "{0} pre-selected elements.",
        n );
 
      // If two or more model pipes were pre-
      // selected, use the first two encountered.
 
      if( 1 < n )
      {
        foreach( Element e in sel.Elements )
        {
          Pipe c = e as Pipe;
 
          if( null != c )
          {
            pipes.Add( c );
 
            if( 2 == pipes.Count )
            {
              Debug.Print( "Found two model pipes, "
                + "ignoring everything else." );
 
              break;
            }
          }
        }
      }
 
      // Else, prompt for an 
      // interactive post-selection.
 
      if( 2 != pipes.Count )
      {
        pipes.Clear();
 
        try
        {
          Reference r = sel.PickObject(
            ObjectType.Element,
            new PipeElementSelectionFilter(),
            "Please pick first pipe." );
 
          pipes.Add( doc.GetElement( r.ElementId )
            as Pipe );
        }
        catch( Autodesk.Revit.Exceptions
          .OperationCanceledException )
        {
          return Result.Cancelled;
        }
 
        try
        {
          Reference r = sel.PickObject(
            ObjectType.Element,
            new PipeElementSelectionFilter(),
            "Please pick second pipe." );
 
          pipes.Add( doc.GetElement( r.ElementId )
            as Pipe );
        }
        catch( Autodesk.Revit.Exceptions
          .OperationCanceledException )
        {
          return Result.Cancelled;
        }
      }
    }
 
    // Extract data from the two selected pipes.
 
    Curve c0 = (pipes[0].Location as LocationCurve).Curve;
    Curve c1 = (pipes[1].Location as LocationCurve).Curve;
 
    if( !(c0 is Line) || !(c1 is Line) )
    {
      message = _prompt
        + " Expected straight pipes.";
 
      return Result.Failed;
    }
 
    XYZ p00 = c0.GetEndPoint( 0 );
    XYZ p01 = c0.GetEndPoint( 1 );
 
    XYZ p10 = c1.GetEndPoint( 0 );
    XYZ p11 = c1.GetEndPoint( 1 );
 
    XYZ v0 = p01 - p00;
    XYZ v1 = p11 - p10;
 
    if( !Util.IsParallel( v0, v1 ) )
    {
      message = _prompt
        + " Expected parallel pipes.";
 
      return Result.Failed;
    }
 
    // Select the two pipe endpoints that are 
    // farthest apart.
 
    XYZ p0 = p00.DistanceTo( p10 ) > p01.DistanceTo( p10 )
      ? p00
      : p01;
 
    XYZ p1 = p10.DistanceTo( p0 ) > p11.DistanceTo( p0 )
      ? p10
      : p11;
 
    XYZ pm = 0.5 * ( p0 + p1 );
 
    XYZ v = p1 - p0;
 
    if( Util.IsParallel( v, v0 ) )
    {
      message = "The selected pipes are colinear.";
      return Result.Failed;
    }
 
    XYZ z = v.CrossProduct( v1 );
    XYZ w = z.CrossProduct( v1 ).Normalize();
 
    // Offset distance perpendicular to pipe direction
 
    double distanceAcross = Math.Abs(
      v.DotProduct( w ) );
 
    // Distance between endpoints parallel 
    // to pipe direction
 
    double distanceAlong = Math.Abs(
      v.DotProduct( v1.Normalize() ) );
 
    Debug.Assert( Util.IsEqual( v.GetLength(),
      Math.Sqrt( distanceAcross * distanceAcross
        + distanceAlong * distanceAlong ) ),
      "expected Pythagorean equality here" );
 
    // The required offset pipe angle.
 
    double angle = 45 * Math.PI / 180.0;
 
    // The angle on the other side.
 
    double angle2 = 0.5 * Math.PI - angle;
 
    double length = distanceAcross * Math.Tan( angle2 );
 
    double halfLength = 0.5 * length;
 
    // How long should the pipe stubs become?
 
    double remainingPipeLength
      = 0.5 * (distanceAlong - length);
 
    if( 0 > v1.DotProduct( v ) )
    {
      v1.Negate();
    }
 
    v1 = v1.Normalize();
 
    XYZ q0 = p0 + remainingPipeLength * v1;
 
    XYZ q1 = p1 - remainingPipeLength * v1;
 
    using( Transaction tx = new Transaction( doc ) )
    {
      tx.Start( "Rolling Offset" );
 
      // Trim or extend existing pipes
 
      (pipes[0].Location as LocationCurve).Curve
        = Line.CreateBound( p0, q0 );
 
      (pipes[1].Location as LocationCurve).Curve
        = Line.CreateBound( p1, q1 );
 
      // Add a model line for the rolling offset pipe
 
      Creator creator = new Creator( doc );
 
      Line line = Line.CreateBound( q0, q1 );
 
      creator.CreateModelCurve( line );
 
      tx.Commit();
    }
    return Result.Succeeded;
  }
}

I hope you find this interesting and useful.

Here are two comments I received on this from Harry and Matt:

• I'm pretty sure this is the most bad-ass thing anyone did at the Hackathon. Nice work Jeremy!
• I second that! I wasn't there but I will pretend I was!

The code presented above is available from The Building Coder samples GitHub repository, and the version discussed here is release 2014.0.106.1.

Tere hommikust!

Sustainably Chugging Along

I continue chugging along here, mainly just answering cases.

January and February tend to be peaceful for me after the extreme travelling and conferencing in December.

I will also be reducing my overdue vacation time in the next couple of months, so expect another break or two in the flow.

Here are today's topics I find interesting or have been looking into myself:

• Autodesk corporate sustainability
• AU 2013 classes available on demand
• AllViews Revit SDK sample enhancement
• Revit API methods that regenerate
• Programmatic Element cutting

Autodesk Corporate Sustainability

Matching the great work done by the Building Performance Analysis team, making strong use of Revit and BIM technologies, Autodesk as a company has committed to reducing its carbon emissions per dollar contribution to GDP by over 9% year over year through 2020, an incredibly long-range goal for a technology company. A review of corporate emissions performance recognized Autodesk and its Sustainability Solutions team as absolute leaders in this area, demonstrating 'tremendous leadership in shaping corporate sustainability metrics to be more grounded in science.'

AU 2013 Classes Available on Demand

What skills could advance your career? Recordings of over 200 classes have been posted online, along with presentations and handouts for the rest of the more 600 classes presented at Autodesk University 2013 in Las Vegas. You can easily get advanced training, explore a new topic, or peer into the future of design software by signing up for a free Autodesk account and starting to learn right away. Here is the AU online overview and a short URL for it.

AllViews Revit SDK Sample Enhancement

Dale Bartlett very kindly provided an enhancement to the AllViews Revit SDK sample. Says he:

The RvtSamples > Views > All Views command retrieves all of the loaded Title Blocks for user selection in the creation of a series of sheets. The code actually builds a collection of Type names using the GetTitleBlocks method, rather than Family:Type names. If each Title Block has a default Type of 'Type 1' (recommended), the following is the result:

Selecting one will result in the first found Type (ChooseTitleBlock) rather than the specific Family:Type.

The above test project contains the following Title Block Families:

If a Family has no Types defined, then the default Type name is always listed the same as the Family name, so in most cases the code would work. I guess that is why it hasn’t been picked up previously.

I fixed this by adding a concatenated FamilyName:FamilyTypeName to the list, and searching for the same to return the appropriate FamilySymbol.Id in the following two methods:

• ChooseTitleBlock
• GetTitleBlocks

Here is the resulting modified and tested code:

  /// <summary>
  /// Retrieve the title block to be generated by its name.
  /// </summary>
  /// <param name="name">The title block name</param>
  public void ChooseTitleBlock( string name )
  {
    if( string.IsNullOrEmpty( name ) )
    {
      throw new ArgumentNullException( "name" );
    }
 
    foreach( FamilySymbol f in m_allTitleBlocks )
    {
      // Original SDK code returns first family 
      // symbol found, e.g. "Type 1" etc.
 
      //if( name.Equals( f.Name ) )
 
      // Replacement by DJB checks for concatenated 
      // family name and type name
 
      if( name.Equals( f.Family.Name
        + ":" + f.Name ) )
      {
        m_titleBlock = f;
        return;
      }
    }
  }
 
  /// <summary>
  /// Retrieve all available title blocks in 
  /// the currently active document.
  /// </summary>
  /// <param name="doc">The currently active document</param>
  private void GetTitleBlocks( Document doc )
  {
    FilteredElementCollector filteredElementCollector
      = new FilteredElementCollector( doc );
 
    filteredElementCollector.OfClass(
      typeof( FamilySymbol ) );
 
    filteredElementCollector.OfCategory(
      BuiltInCategory.OST_TitleBlocks );
 
    m_allTitleBlocks = filteredElementCollector
      .ToElements();
 
    if( 0 == m_allTitleBlocks.Count )
    {
      throw new InvalidOperationException(
        "There is no title block to generate sheet." );
    }
 
    foreach( Element element in m_allTitleBlocks )
    {
      FamilySymbol f = element as FamilySymbol;
 
      // Original SDK code saves only symbol name.
 
      //AllTitleBlocksNames.Add( f.Name );
 
      // Replacement by DJB saves concatenated 
      // family name and type name to ensure 
      // uniqueness in list.
 
      AllTitleBlocksNames.Add( f.Family.Name
        + ":" + f.Name );
 
      if( null == m_titleBlock )
      {
        m_titleBlock = f;
      }
    }
  }

Did I win a t-shirt?

Many thanks for all your help over the year via your Building Coder blog. A lot of people appreciate your efforts I know.

Many thanks to you, Dale, for discovering, fixing and sharing the solution for this issue!

Revit API Methods that Regenerate

A recent ADN case concerns a performance issue creating a large number of roofs, and why each one of them triggers a regeneration of the model:

Question: I have a program that uses a temporary transaction inside a transaction group to make changes to the model. It creates a large number of footprint roofs to represent rooms in a 3D view and shows the user the result in a preview control. However, this is taking a long time in a large model. In the debugger, I can see that each call to Document.Create.NewFootPrintRoof is taking up to 10 seconds. The user interface displays the 'Regenerating' message in the status bar several times before my call returns, so it appears that the model is being regenerated at least once for each call.

How can that be?

I am specifying manual regeneration mode. Revit is not supposed to regenerate the model until a transaction is closed, isn't it? How can I generate all the roofs without triggering a regeneration for each one?

Answer: Sorry, this is working as expected. Unfortunately, setting up the roof properly and ensuring consistency requires an internal regeneration.

This is pointed out explicitly in the Revit API documentation in RevitAPI.chm, which says the following about this method: "This method will regenerate the document even in manual regeneration mode."

There are a number of other Revit API methods that regenerate the model internally as well.

You can find them by searching the help file for the string above, which returns the following:

To see yet a couple of entries more, just search for "regenerate manual regeneration mode":

Response: In the case above, switching to using floors instead of roofs speeded the process up by a factor of more than ten.

Out of curiosity: is there a reason that roof creation regenerates and floor creation does not?

Answer: Sure: a floor is generally flat, whereas a roof with angles can generate an extremely complex shape.

Programmatic Element Cutting

A frequent question is how to cut Revit elements with each other, both in the family and project contexts.

Here is a recent incarnation of the topic that reached me both as an ADN case and a Revit API forum discussion thread on cutting elements:

Question: I'm trying to write a tool that will cut a beam to a reference plane and I'm not sure if it's possible in the API with SolidSolidCutUtils because of the element type that is a beam or reference plane. Here's my code so far:

  TaskDialog.Show( "Step 1",
    "Choose an element as a reference to cut to." );
 
  Reference eRef = m_document.Selection.PickObject(
    ObjectType.Element, "Please reference line." );
 
  TaskDialog.Show( "Step 2", "Choose an element to cut." );
  Reference eCut = m_document.Selection.PickObject(
    ObjectType.Element, "Please pick an element." );
 
  if( eRef != null
    && eRef.ElementId != ElementId.InvalidElementId
    && eCut != null
    && eCut.ElementId != ElementId.InvalidElementId )
  {
    CutElement( eRef, eCut, m_document, doc, activeDoc );
  }
 
  void CutElement( Reference eRef, Reference eCut,
    UIDocument m_document, Document doc,
    Document activeDoc)
  {
    //TaskDialog.Show("Step 2", "Here");
 
    int CutElement = m_document.Document
      .GetElement(eCut).Id.IntegerValue;
    int ReferenceLine = m_document.Document
      .GetElement(eRef).Id.IntegerValue;
 
    Element solidToBeCut = activeDoc.GetElement(
      new ElementId(CutElement));
 
    Element cuttingSolid = activeDoc.GetElement(
      new ElementId(ReferenceLine));
 
    Transaction transaction = new Transaction(activeDoc);
    transaction.Start("AddCutBetweenSolids");
    SolidSolidCutUtils.AddCutBetweenSolids(
      activeDoc, solidToBeCut, cuttingSolid);
    transaction.Commit();
  }

The problem is I get an error at AddCutBetweenSolids that the parameter solidToBeCut isn't of the right type. Is there another method that would accomplish what I'm trying to do or is there a way to fix this method to do what I want?

Answer: There are several different possible ways to perform Boolean operations between Revit elements.

I put together a collection of pointers to various discussions on The Building Coder concerning 3D Booleans and Cutting Elements to help answer your question.

In many cases, within the family environment, the approach you are attempting using SolidSolidCutUtils is one of the best and most effective options.

However, just as you have discovered, it places certain requirements on the input solids.

Just as its name implies, the cutting solid must be a solid.

A reference line definitely does not fulfil this requirement.

You will have to create a solid somehow.

Here is one suggestion of how to achieve this:

Use the reference line you already have and another one perpendicular to it to define a plane, define a large extruded cube based on that plane, and subtract that from your main body.

Starting to Clean Up For the Break

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

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

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

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

Here is a nice little anecdote to illustrate the principle:

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

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

The master asks, "Have you had breakfast?"

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

"Then go and wash your eating bowl."

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

Autodesk University Classes Ready for Viewing and Download

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

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

Here are the results of searching for my classes:

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

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

Building Performance Analysis Update

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

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

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

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

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

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

Expect more in this area!

Daylighting Analysis Tool for Revit Update

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

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

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

The features provided by the new update include:

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

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

AU Day 3, ReCap & Cloud-based Round-trip Model Editing

When you get to read this, I will be sitting in a plane at 30'000 feet over the middle of the Atlantic Ocean... or somewhere over Greenland, whatever.

Thursday was the third and last day of Autodesk University.

I went out for a quick beer with some of my ex-Autodesk-colleagues from decades ago on Wednesday evening, and a very nice time was had by all.

It turned out to be not quite so quick, however, and not just one beer, and I woke up next morning suffering dire consequences.

I would strongly sustain that they were due to the fact that the brews I sampled to not adhere to the strict and sensible purity rules. I would never have expected such a huge difference in after effects.

Luckily, though, I did wake up, initially thinking that my cloud-based round-trip 2D Revit model editing class would be later in the day. Even more luckily, I decided to switch on the computer and look at the schedule.

Imagine my shock to discover that it was scheduled for 8:00 am.

Anyway, I made it, and everything went really well, and now I am sitting at the airport and the plane is delayed.

These are my main activities of the day:

• Cloud-based round-trip 2D Revit model editing
• Replace Idling by an External Event
• ReCap reality capture and its REST API

Cloud-based Round-trip 2D Revit Model Editing

I presented my class DV1736 – Cloud-Based, Real-Time, Round-Trip, 2D Revit Model Editing on Any Mobile Device.

This is the second time I present my super simple solution open source based solution for this task.

The first was at the Autodesk internal Tech Summit in June (overview, 30-minute pre-recorded video and live recording).

This time around, I had 90 minutes – instead of 30 – to discuss the topic in much more completeness and detail, which felt very good.

Here is the class handout and slide deck.

A recording will come later, once the AU technical staff have completed and made it available.

Replace Idling by an External Event

During the Revit API roundtable on Wednesday, I finally realised what I should have been doing all along instead of fiddling with the Idling event.

I wish someone else would have noticed, thought of this, told me much earlier, and we would not all have had to wait until I finally thought of it myself.

This planet sure can feel like a lonely place sometimes.

Anyway, I now realised that I can significantly reduce the overhead and sluggishness of the Idling event by using an external event instead that I define myself.

An external event would allow me to vary the number of checks I make per second freely, relinquishing control in between, and only bother Revit when there really is something for it to do, i.e. a pending database update to be integrated into the BIM.

I can't wait to implement and test this!

ReCap reality capture and its REST API

At the last moment before leaving for the return flight, I discovered the class by Stephane Negri, Software Development Manager, Autodesk, RC3176 – Put Your Mind at REST: Extend Your Application to Reality Capture:

The reality capture group at Autodesk is working on ways to acquire, manipulate, or analyse real scene data using laser scans or photos through Autodesk ReCap products. While several AU classes demonstrate ReCap use and workflows associated with these products, this class focuses on how to programmatically access the reality capture web API to create or extend an application. We start with a quick overview of basic photogrammetry concepts and image parameters, then approach the reality capture REST API and discuss how to define a photo scene from multiple photos and create a dense 3D mesh, also covering some of the advanced features that are available to customize and refine the process. The class concludes with a complete example written in PHP.

I already mentioned this topic in my overview of the cloud & mobile platform web service APIs provided during the ADN DevDay conference on Monday.

Here are my notes from Stephane's class, with absolutely no guarantee for correctness:

Autodesk offers several different browser-based user interfaces for different reality capture scenarios.

They all use the same underlying ReCap REST API.

You need a special developer key to make use of the API. To obtain one, please contact ADN and ask to become a pilot partner.

Stephane presented a manual demo to clarify the user interface, available functionality and usage workflow.

You sign in with the standard Autodesk single sign-in.

The project gallery presents impressive examples of the kind of models that can be achieved.

He created a new project using only three photos.

Very simple workflow: create a new project, upload photos, wait and retrieve the result.

Photos must be of high quality, good lighting and equipment and overlapping, e.g. with each point visible in at least three pictures.

Quality is more important than quantity.

ReCap is built on Amazon web services, using queues to manage jobs.

The basic API workflow matches the manual approach: create photoscene, upload files, progress check, retrieve results.

Authentication using Oxygen, and Autodesk service based on OAuth 1.0, a three-legged authentication based on HTTP header data.

Documentation is public and embedded in the service, generated by the Swagger framework for describing, producing, consuming, and visualizing RESTful web services.

You can easily try out the UI workflow via the API using manual REST calls.

The results of each REST call are returned in either JSON or XML.

For more information, please contact recap.api@autodesk.com.

Stephane also presented some of the current pilot partners and their work, some of which was also being shown in the AU exhibition:

• SoundFit custom fit ear gear, creating a precise model of the inner space within the ear for prosthetics, a fully automated complete custom application.
• Kubit, dealing with AutoCAD applications for real-world as-built capturing.
• Skycatch, providing a low cost, highly flexible, intelligent & scalable aerial robotics platform.

Tilo Pfliegner of Kubit demonstrated easy integration of calibrated photos, point clouds and ReCap models into AutoCAD.

Point clouds are sometimes too imprecise for modelling needs. Using photos directly instead is better, because they are often more precise, and the photo quality is often better than the generated point cloud. He listed the following applications:

• Photo modelling
• Phototracing
• Monoplotting
• Creation of image plans
• Orthophotos
• Unwinding

Chris Bumgardner of SkyCatch presented their Recap API integration for fully autonomous unmanned flying vehicles.

A typical use case might be the generation of daily 3D models for construction customers.

They have implemented a server-to-server integration using Recap 3.1 API, Node.js server-side JavaScript, OAuth, request etc.

You can use a viewer such as Sketchfab to view the resulting OBJ model. Sketchfab is a web service to publish and display interactive 3D models. No plugin required: upload your model, embed it, share it, done.

This makes it extremely easy to embed the resulting model into web browser, for example.

Again, high quality images are more important than quantity, e.g., four images may be perfectly sufficient.

Use high-resolution images. The resulting accuracy may reach down to one single pixel level. Go closer if you use low resolution.

How to scale the resulting model properly to the real world? You can use a template file, have known camera positions, set GPS coordinates, measure the real-world sample, etc.

GoPro has a fisheye distortion; switch it off with StitchingCreateInputFile = 1.

The Exif data within each image tells you the source of it, e.g. to recognize GoPro images.

You don't have to add any marker points, just make sure the surfaces are not too bland and uniform.

Many thanks to Stephane, Tilo and Chris for the interesting presentation.

AU Day 2, Worksharing and Revit 2014 API Roundtables

Here is my report on Wednesday at Autodesk University, following the DevDay pre-event conference on Monday and the first real day at AU on Tuesday.

These are my main activities of the day in chronological order, plus pointers to a fantastic class or two that I missed and want to highlight anyway:

• Virtually human – modelling the human body using BIM
• Design to fabrication
• Revit add-ins that cooperate with worksharing
• Worksharing roundtable
• Revit API roundtable

Virtually human – modelling the human body using BIM

This is an utterly fantastic presentation on highly professional worldwide BIM collaboration for fun by Mike Slessor, Jonathan Lock, Ken Enright and Casey Rutland of ARUP. I was unfortunately unable to attend, since it took place at the exact same time as my first class on advanced Revit 2014 API features and samples early Tuesday morning: MP2845 – Virtually Human: Modelling the Human Body Inside and Out Using BIM Platforms. They say:

The study of human anatomy has traditionally been the domain of physicians, dentists, physiotherapists, nurses, paramedics, and other health professionals. What happens when you let building designers have a crack at replicating it? This class provides you with the opportunity to meet Project OVE, Arup’s virtual human. OVE has a full structural skeleton and respiratory system. OVE sweats, gets hungry, and even has a heart. We are still working on the operating system but OVE has a huge brain that will act as the main control centre when finished. However, OVE is also more than just an artificial replication of the human body. Creating an intelligent version of OVE required us to exploit the full potential of Revit as a state-of-the-art BIM (Body Information Modelling) tool.

Here is the 161-page class handout PDF, which I find absolutely fascinating.

Design to Fabrication

Another class that I was unfortunately unable to attend yet take a special interest in is William Spier's FB2938 – Design to Fabrication: Design, Validate, and Fabricate Anything Between Revit and Inventor.

William asked me to implement the ExportCncFab add-in, originally published in March under the name ExportWallboard to automatically isolate and export wall parts individually to DXF for CNC fabrication.

Now, after a minute last-minute hiccup that we solved end of last week and over the weekend, the add-in is up and running as expected, including the external application driving the user interface and the new shared parameter generation command.

The updated version is available from the ExportCncFab GitHub repository, and the current version is release 2014.0.0.11.

This is only one of the many powerful fabrication solutions and paths that William developed and presents, though.

Here is current version of his complete handout and slide deck.

Revit Add-ins that Cooperate with Worksharing

The one and only class that I was able to participate in so far without carrying any responsibility whatsoever for myself was Scott Conover's DV1888 – Facing the Elephant in the Room: Making Revit Add-ins That Cooperate with Worksharing.

I am so glad that I did, because the information presented there is absolutely invaluable.

At the moment, it is available only from the Autodesk University site.

We will certainly return to this topic and publish all the material as soon as it is finalised.

This is too important to ignore, and too complex to understand without some expert guidance.

Worksharing Roundtable

The worksharing class was followed by the roundtable session DV3464-R – Making Revit Add-ins That Cooperate with Worksharing with a dozen expert Revit API and product users plus Sasha, Scott and Jeremy.

I took some notes, and so did Sasha and Scott, so we will wait with publishing those until they have been consolidated.

Revit API Roundtable

The next class that I took responsibility for myself is the DV1914 Revit API roundtable inviting the participants to interact with a panel of Revit API experts from Autodesk to get answers to their questions and discuss all relevant customisation topics of their choice. This is the perfect forum to get to know better some of the people who shape the APIs you work with and to explain your views, ideas, and problems directly face-to-face.

Many thanks to all the more than 50 participants of this session, and especially to the following panellists who collectively answered the many interesting questions that were raised:

• Angel Velez, Revit Development
• Augusto Gonçalves, ADN
• Jeremy Tammik, ADN
• Miroslav Schonauer, Autodesk Consulting
• Scott Conover, Revit Development
• Sasha Crotty, Revit Development

This session was recorded. I uploaded a rather low quality version of the 60-minute recording. Luckily, a better quality one was made in parallel by the AU technical staff, and we will have to wait a while for that to become available.

Here are the questions and answers brought up during this roundtable session, almost unchanged from the original form they were jotted down in, and also added to the updated handout:

[q] modify visibility of linked files per view?
[a] currently no API access.

[q] modify selection from a modeless context, how to update view?
[a] check it out in UR2, it should be fixed.

[q] Revit materials. when i try to read bitmap from asset, the bitmap path in the asset property is not consistent. for some materials you can access the full bitmap path, but sometimes there is no entry for the bitmap itself. is there a better way to get the bitmap from materials?
[a] going forward, we definitely are looking at better access to material asset info.

[q] Revit API preview window to display sheets will not dynamically update when we change sheet name or number, so we have to create a new sheet in order to force it to update. part 2: preview window. will it be made more dynamic?
[a] i am not aware of any such issue, please report to ADN, we want to hear about this. post it on the forum so we can track it. we will research and submit an issue if needed. part 2, improvements: we can discuss a little more what you are looking for. some of our exports use the preview window, you can toggle things on and off, we need to hear what you need.

[q] acad has COM + .NET interface to access from outside, open and close documents and start up and shut down autocad. is this possible in Revit?
[a] we do not currently have that. use the external event mechanism instead.

[q] i have an app that opens Revit and configures worksets. it crashes now and again and the problem is reproducible. response: it only happens when you are using Revit server, and the API is not fully supported for that.
[a] the API should support that, there are no limitations for Revit server.

[q] working with schedules and accessing a parameter from schedule or from an element there is a difference. the id is the same. wanted to distinguish between a project and a shared param with the same name.
[a] element ids are used to represent elements, parameters and categories. for params, the id may be negative, e.g. bip, or non-negative, custom or shared. when you call get element on that id, it returns the parameter definition. probably that object does not have an exposed subclass in that context. there is difference between newer and older environments, and the schedule API is newer.

[q] use cut and paste API to import new sheets. the DuplicateViews SDK sample does drafting views and schedules. any advice for sheets?
[a] the mechanics for sheets would be the same. probably best to copy them together, because then Revit can do an optimal job of maintaining relationships. bring in the empty drafting views and settings all together. DuplicateViews demonstrates these two steps.

[q] any plans for enhancing this?
[a] it is already perfect. Revit uses it internally also.

[q] non-technical: collaboration between dynamo and API team?
[a] there is a group of dynamo guys all around us, they are in the same office. we try to expand Revit development in all directions.

[q] purge all. any chance of exposing that, purge unused?
[a] who needs a purge API? lots.

[q] convert an element from linked file and put them into the host document. can i do that?
[a] copy monitor approach lets them remain in the link, and the copy paste API can bring them in properly. use copy paste and then delete the linked element. that will require unloading it. depending on what element you ant to bring over, it may run into problems trying to separate it from its relationships. it might bring it in with the right shape. otherwise you might need to read boundaries and recreate it. if you bring it in as is it will be looking for sketch curves in the wrong place.

[q] macro ide. structural company, little API programs passed out to customers, using macro to transfer to customer, but it is not so simple. to transfer macros to customer it is a bit more complicated.
[a] you could use the python shell. why not make it an external command and send the dll? then the user does not have to touch anything. you can embed the macro in the model, and then there is no code to transfer. the macro does actually generate a mini little hidden DLL that you can transfer to the customer.

[q] add-in existing with a project. can they be bundled?
[a] only macros and dynamo scripts. the exchange store is actually the most official avenue. we are interested in people sharing code, but it also worries some. you have many options.

[q] furniture in Revit families including 150 types. easy way to create blocks of every time. create a symbol library. can that be dome programmatically?
[a] yes, simple to solve, has been published.

[q] reload the keynote file?
[a] yes, we are looking at that for the future. right now it can be solved using an autohotkey script. in 2014 you can also post the command.

[q] can i access the Revit line pattern from a Revit style? line weight is available.
[a] augusto wrote a code about that a few weeks ago. you have to search the assets.

[q] create or control underlays in a section view, like the ones you have in plan view? structural engineering in chile requires you to show the projected elements in front and behind. underlays in the views would solve this.
[a] probably not exposed. that si a good request to make. we have 11500methods and classes, we do not always know. augosto saw a solution involving moving the selection a bit. this is not API functionality, but basic Revit platform functionality expansion request, been requested for ten years.

[q] extensible storage available in families?
[a] yes. there is a sample that demonstrates this in the original estorage au materials.

[q] basic file info, transmission data. can a few more areas be opened up, e.g. view sheet list? now i have to open the file, export the view list, close the file.
[a] yes, that is the current approach. file a request, please.

[q] furniture geometry has a huge amount of unique vertices. how can i reduce that? i need it for a webgl viewer.
[a] Revit is good at optimising. something is curved. Revit likes to triangulate things. there are some knobs that you can use to turn down the triangulation. ifc uses the solid tessellation routine added in 2014. if you are exporting solids, take a look at that. the normal tessellation routines do not line up adjacent faces. doing the whole solid in one go is better. another approach is the custom exporter. then you do not need to think about each element.

[q] document changed event tracks changes. how do i know exactly what changed, and what the old value was?
[a] you have to cache all the values of interest beforehand. we have a similar request around what was deleted.

[q] dual monitor support, how can i take some things outside of the Revit window? it seems to work on autocad.
[a] you can create a modeless dialogue, attach it to the Revit parent window and drag it off the screen.

[q] single core. multicore machine. how can i know what thread Revit is using?
[a] the windows processes can be queried. look for the revit.exe process and the .NET Process library. this is Windows API, not Revit API.

[q] some params have type of colour and bring up a dialogue when the user edits them. can i create a shared param to store a colour as well?
[a] Revit implements some parameters that map to custom behaviour and launch dialogue. this is not accessible programmatically.

[q] can i raycast onto a non-planar surface?
[a] the ReferenceIntersector ray cast utility can be used, but only ray by ray. the extrusion analyser only goes onto a flat plane. you could make repeated calls to the extrusion analyser call for each facet of the tessellated surface.

Many thanks to all who joined in here!

AU Day 1, Revit 2014 API Class and Bounding Box Rotation

Tuesday was the first real day at AU after the DevDay pre-event conference yesterday.

Here are my main activities of the day in chronological order:

• Advanced Revit 2014 API features and samples
• AU Keynote by Jeff and Carl
• DevLab and bounding box rotation
• Adding a marker at the Revit project origin
• Download

Advanced Revit 2014 API Features and Samples

I presented my first class DV2010 – Advanced Revit 2014 API Features and Samples right away starting at the very first moment of AU, at eight in the morning.

Here is the most up-to-date handout and slide deck.

Keynote

As usual, the keynote presentation was given by Jeff Kowalski and Carl Bass, with Jeff focusing on ideas and long-term vision and Carl presenting real live usage examples of existing products.

Jeff expounded on the power and advantages of collaboration and open source, and how the Autodesk 360 platform supports that. He suggested picking a class by chance, to learn something completely new, mentioned reverse mentoring, where young people mentor older experienced folk, pointed out how much there is to learn from each other, e.g. using reverse innovation, consciously looking outside, beyond what you and everybody else thinks is possible, to learn, unlearn and relearn.

Carl highlighted a number of different original and creative companies making use of new technologies to save huge amounts of time and effort, e.g.:

• Orphanage guitars via fusion 360 to create custom made guitars involving the customer directly in the process.
• Aston Martin creating a new car, concept sketches, Sketchbook, Alias, CNC-generated clay model, post processed including hand sculpting, laser scanned to bring it back into Alias, completing the cycle to market in record time.
• PLM 360 cloud-based example with a four month adoption period, to search for data and create documentation
• Prosthetic leg collaboration project using A360 and CAM 360.
• Airport project complexity BIM developer share coordinate using BIM 360 Glue thousands of hours saved BIM 360 Field solve problems in real-time, Infraworks 360, ReCap point cloud image based 3D modelling, the only input you can really trust, saving thousands of hours of modelling work.
• BioLite building a stove scaled up by a factor of 500 from the normal design on short notice using SIM 360.
• Bot & Dolly film and robots Maya animate robots in real life the way you would normally animate virtual characters. Complete control of robot motion in time and space. Robot "Iris" danced for us. For a sample, look at Box on YouTube.

According to Carl, the most important things to look at in the coming days are Autodesk 360 and computational design, e.g. Dynamo. It currently drives Revit. Being open source, it can be adapted by anyone for other products as well, and an implementation driving Inventor has already been unveiled.

Lots of great new technology to discover, and more than 500 classes to choose from.

DevLab and Bounding Box Rotation

DevLab was active, lots of questions addressed.

One little issue I was able to capture was this snippet of code to calculate the max and min of a rotated bounding box, initially inspired by Angel Velez, Revit developer, and heavily edited by your humble scribe:

Angel pointed out that if you wish to calculate the result of rotating a bounding box representing a rectangle around the origin in the XY plane, you cannot simply rotate the min and max points, because the rotated max point may easily end up being 'smaller' in some coordinate than the rotated min.

One way to work around that is to extract all four bounding box corners, rotate each of them and determine new min and max values from those.

I implemented this little helper method to generate the four XY corner points of a bounding box, flattened onto its minimum Z elevation:

  /// <summary>
  /// Return the four XYZ corners of the given 
  /// bounding box in the XY plane at the minimum 
  /// Z elevation in the order lower left, lower 
  /// right, upper right, upper left:
  /// </summary>
  public static XYZ[] GetCorners( BoundingBoxXYZ b )
  {
    double z = b.Min.Z;
 
    return new XYZ[] {
      new XYZ( b.Min.X, b.Min.Y, z ),
      new XYZ( b.Max.X, b.Min.Y, z ),
      new XYZ( b.Max.X, b.Max.Y, z ),
      new XYZ( b.Min.X, b.Max.Y, z )
    };
  }

In order to be able to use the standard .NET Min and Max methods to extract the min and max points from the rotated corners, I need to use a flavour of the XYZ point and vector class which implements the IComparable interface.

To obtain that, I implemented this little XyzComparable wrapper class:

  /// <summary> 
  /// XYZ wrapper class implementing IComparable. 
  /// </summary> 
  class XyzComparable : XYZ, IComparable<XYZ>
  {
    public XyzComparable( XYZ a )
      : base( a.X, a.Y, a.Z )
    {
    }
 
    int IComparable<XYZ>.CompareTo( XYZ a )
    {
      return Util.Compare( this, a );
    }
  }

It makes use of my pre-existing XYZ Compare utility method:

  public static int Compare( XYZ p, XYZ q )
  {
    int d = Compare( p.X, q.X );
 
    if( 0 == d )
    {
      d = Compare( p.Y, q.Y );
 
      if( 0 == d )
      {
        d = Compare( p.Z, q.Z );
      }
    }
    return d;
  }

With all of that in place, the bounding box rotation ends up quite simple and readable:

  /// <summary>
  /// Return a rotated bounding box around 
  /// the origin in the XY plane.
  /// We cannot just rotate the min and max points, 
  /// because the rotated max point may easily end
  /// up being 'smaller' in some coordinate than the 
  /// min. To work around that, we extract all four 
  /// bounding box corners, rotate each of them and
  /// determine new min and max values from those.
  /// </summary>
  private static BoundingBoxXYZ RotateBoundingBox(
    BoundingBoxXYZ b,
    Transform t )
  {
    double height = b.Max.Z - b.Min.Z;
 
    // Four corners: lower left, lower right, 
    // upper right, upper left:
 
    XYZ[] corners = Util.GetCorners( b );
 
    XyzComparable[] cornersTransformed
      = corners.Select<XYZ, XyzComparable>(
        p => new XyzComparable( t.OfPoint( p ) ) )
          .ToArray();
 
    b.Min = cornersTransformed.Min();
    b.Max = cornersTransformed.Max();
    b.Max += height * XYZ.BasisZ;
 
    return b;
  }

In order to test this new functionality, I dug up the old CmdBoundingBox implementation from The Building Coder samples, from one of the very first posts back in the year 2008.

It prompts you to select an element and used to just report its bounding box coordinates in a message box.

I modified that to draw model lines for the box instead, again making use of the GetCorners method defined above to extract the four vertices required. This also obviously requires changing the command's transaction mode from read-only to manual and adding a transaction, since the model line creation modifies the database.

To test the rotation functionality, I call the RotateBoundingBox method with a 60 degree rotation transformation and print and display the result like this:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication app = commandData.Application;
  UIDocument uidoc = app.ActiveUIDocument;
  Document doc = uidoc.Document;
 
  Element e = Util.SelectSingleElement(
    uidoc, "an element" );
 
  if( null == e )
  {
    message = "No element selected";
    return Result.Failed;
  }
 
  // Trying to call this property returns the
  // compile time error: Property, indexer, or
  // event 'BoundingBox' is not supported by
  // the language; try directly calling
  // accessor method 'get_BoundingBox( View )'
 
  //BoundingBoxXYZ b = e.BoundingBox[null];
 
  View v = null;
 
  BoundingBoxXYZ b = e.get_BoundingBox( v );
 
  if( null == b )
  {
    v = commandData.View;
    b = e.get_BoundingBox( v );
  }
 
  if( null == b )
  {
    Util.InfoMsg(
      Util.ElementDescription( e )
      + " has no bounding box." );
  }
  else
  {
    using( Transaction tx = new Transaction( doc ) )
    {
      tx.Start( "Draw Model Line Bounding Box Outline" );
 
      Debug.Assert( b.Transform.IsIdentity,
        "expected identity bounding box transform" );
 
      string in_view = ( null == v )
        ? "model space"
        : "view " + v.Name;
 
      Util.InfoMsg( string.Format(
        "Element bounding box of {0} in "
        + "{1} extends from {2} to {3}.",
        Util.ElementDescription( e ),
        in_view,
        Util.PointString( b.Min ),
        Util.PointString( b.Max ) ) );
 
      Creator creator = new Creator( doc );
 
      creator.DrawPolygon( new List<XYZ>(
        Util.GetCorners( b ) ) );
 
      Transform rotation = Transform.CreateRotation(
        XYZ.BasisZ, 60 * Math.PI / 180.0 );
 
      b = RotateBoundingBox( b, rotation );
 
      Util.InfoMsg( string.Format(
        "Bounding box rotated by 60 degrees "
        + "extends from {0} to {1}.",
        Util.PointString( b.Min ),
        Util.PointString( b.Max ) ) );
 
      creator.DrawPolygon( new List<XYZ>(
        Util.GetCorners( b ) ) );
 
      tx.Commit();
    }
  }
  return Result.Succeeded;
}

I tested that on a single wall element, with the following resulting model lines displaying the original and rotated bounding boxes:

See how skewed it gets?

Addemdum by Angel Velez: this code assumes that the rotation is in XY only, hence the 'flattening' of the bounding box cube to 4 points. If you wanted to make it applicable to a truly arbitrary rotation, you would take the 8 points of the cube – so factor Min.Z and Max.Z into it – then you wouldn’t have to do any 'add Z back in at the end' hacks. Of course, you also have to do an extra 4 transforms.

That would add a significant amount of complexity, however, and the above should cover the most common cases by far.

Adding a Marker at the Revit Project Origin

In order to understand properly and analyse the rotation results, we obviously need to know around which point it is taking place.

It would be handy to add a marker at a specific point in the Revit model, in this case at the origin.

One way to achieve this, was described by the Revit Clinic discussing the two mile barrier: "If you want to be sure, the easiest method is to import a DWG file that contains a circle or X at AutoCAD's 0,0 and make sure to select the option origin-to-origin while importing the DWG file. This will show you exactly where the Revit origin is located (centre of the circle or x). Here is an AutoCAD DWG file with a symbol at the origin."

When importing the DWG into my model using Insert > Import CAD, I left all the default setting values except the following:

• Import units: Custom factor: 0.5
• Positioning: Auto - Origin to Origin

You can admire the resulting origin marker in the screen snapshot above, along with model lines displaying the positions of the original and rotated bounding box.

Download

The updated version of this command is available from The Building Coder samples GitHub repository and the version discussed above is release 2014.0.106.0.

Have fun, and wish me a good quick sleep, since there are only a very few hours left before my next meeting...

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!

Arrival at AU and The Story of Stuff

I arrived safe and sound at AU.

Last week was pretty hectic with preparations for both AU and DevDays.

The weekend was also pretty full.

Unlike previous years, I did not leave Europe until the last possible moment, so no visit to the desert for me this time around.

The reason was my friend Sonja, who invited 100 friends to a half-day 'Be the Change' or Awakening the Dreamer Symposium on Saturday afternoon along the lines of The Pachamama Alliance.

The twenty-minute Story of Stuff presents a summary of some of the aspects we looked at together.

It was very inspiring, although I personally still think I lead a pretty sustainable everyday life.

It felt a bit unsustainable to go off and fly across the Atlantic Ocean the very next day, though.

Anyway, I arrived safe and sound, the DevDay conference is about to begin, and I am looking forward to seeing all of you Revit developers face to face in the next few days!

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!

RoomEditorApp for Revit 2014 on GitHub

I discussed my Revit add-in for my cloud-based, real-time, round-trip, 2D Revit model editing application on any mobile device in depth last spring, with the last update on its implementation status published back in May.

Even at that time, since I was mainly concentrating on the exciting cloud aspects of the application, I had added quite a bit of functionality to the Revit add-in that I never got around to documenting, such as

• External application
• Automatic immediate BIM update from cloud database
• Subscription toggle button

The various aspects that I did already discuss are listed in The Building Coder Desktop category.

By popular demand, I also provided an emergency stop-gap update of the source code for the latest Revit 2013 version during the Sydney Revit API training in July.

I now really have to get going with the preparation of my AU presentations, and one of the unavoidable steps is migrating this application to Revit 2014, which is what I discuss here and now.

Clone and Compile DreamSeat

One of the prerequisites for interacting with the cloud database is obviously uploading and querying of its data.

I use CouchDB as the cloud database and the DreamSeat .NET library to access it from my C# Revit add-in.

To create the library for my add-in to reference, I cloned the DreamSeat GitHub repository to my local system:

  git clone https://github.com/vdaron/DreamSeat

Since it was last built using a newer version of Visual Studio, I had to edit the two first lines in the DreamSeat.sln solution file to be able to use Visual Studio 2010 instead. I simply changed them to read:

Microsoft Visual Studio Solution File, Format Version 11.00
# Visual Studio 2010

No other changes required, the library compiled, and I can add a reference to it to my Revit add-in project.

RoomEditorApp Migration from Revit 2013 to Revit 2014

I created a new Visual Studio solution for a new Revit add-in named RoomEditorApp and copied the code from my old Revit 2013 GetLoops add-in into it.

After the flat migration, the compilation completes and just reports 16 obsolete API usage warnings, which seems pretty good.

I posted the flat migrated version to the GitHub RoomEditorApp repository and created an initial version 2013.0.0.9 to provide a starting point from which to track my changes.

I easily fixed all the warnings, as described in numerous previous discussions, and published version 2014.0.0.10 compiling with zero errors and warnings.

Oops, I also need to change my namespace from GetLoops to RoomEditorApp. This became obvious as soon as I attempted to load the external application in Revit, since it complained about the missing RoomEditorApp.App specified in the add-in manifest, which was still named GetLoops.App. The namespace is correctly specified in version 2014.0.0.11.

Oops again; it next complained on loading into Revit about lacking the embedded icon resources. Luckily, my external application includes assertions that ensure that the required resources are actually found, so I noticed what the problem was. Here is finally version 2014.0.0.12 with icons added and displaying the user interface successfully in Revit 2014:

Installing CouchDB

For testing purposes, I prefer a local installation of my database in addition to the cloud-based one.

That obviously also requires a local installation of the CouchDB database system itself as well.

To create that, simply go to Apache CouchDB, click on 'download', install, and restart the computer.

I install it as a service and later go into the computer management and set the service to be started manually instead of automatically, so it is only available when actually needed.

Replicate the Database

Since I already have my cloud-based application up and running on the Iris Couch cloud CouchDB server from my last experiments, I can simply replicate that.

The database base URL is jt.iriscouch.com/roomedit, whereas the entry point to access and test it is its main application file index.html at jt.iriscouch.com/roomedit/_design/roomedit/index.html.

I can replicate it using the CouchDB Futon interface on my local machine installation, replicating to a new local database named 'roomedit' from the cloud-based database instance:

Conclusion

I am up and running now in Windows 7 and Revit 2014, as opposed to my rather obsolete previous installation based on Windows XP and Revit 2013.

I still have a lot of undocumented features that I would love to discuss here in the Revit side of things.

As said, I need to prepare my AU presentation and handout on this topic.

Whereas the Tech Summit presentation that I worked on in the spring focused heavily on the cloud aspects, the AU presentation will be significantly longer and cover both the cloud database and the Revit add-in features.

Therefore, I can document the missing bits and pieces in the coming weeks as I get my AU material ready, with the deadline for handing in the material on November 15 looming on the horizon.

Back and Preparing for AU and DevDays Conferences

I returned from my nine-day break and am fully invigorated and happily back with the Revit API.

Besides handling questions from developers, I also need to deal with the upcoming yearly conference preparations.

On one hand, we have Autodesk University, for which registration opened and I need to prepare my three classes.

As you know, AU is completely open and public, based on the released Autodesk products, and addresses both end users and developers.

The Autodesk Developer Network ADN, supporting professional developers, holds another yearly series of DevDays conferences that was previously kept pretty hush-hush, as it deals with unreleased products and exclusively addresses developers under non-disclosure agreement.

ADN support was significantly broadened with the introduction of ADN Open last year.

In spite of this initiative, an ADN membership still does provide significant advantages, such as enhanced support, access to released Autodesk products, preview versions of future releases, and the ability to participate in the confidential DevDays conferences.

This year, therefore, we are publicising these events more openly than before, inviting you to join one of our rEvolutionary DevDays conferences.

Before I get to that, though, let me show a few quick impressions from my vacation in Andalusia, e.g. this sunset over Motril:

Look at the detailed range of different beautiful mountain range silhouettes in there:

I finally made it to Cabo de Gata, where I spent a night on the beach under the full moon:

Here is the sunrise at the same place the following morning:

Now, as said, I have the conferences to prepare for and a number of accumulated other issues to catch up with...

Here is the description and worldwide schedule of the ADN DevDays Conferences:

rEvolution – Where Desktop meets the Cloud

Got great ideas for cloud and mobile apps? Want to learn where Autodesk is taking the convergence of desktop computing and cloud technology?

If you are an innovator developing on Autodesk platform technology and have not yet attended an Autodesk Developer Network Conference, join us for a deep dive as we take an in-depth look at Autodesk's newest technologies and the next generation of products coming in 2014. The Autodesk Developer Network is holding its annual, worldwide Developer Day Conference and DevLab in cities around the world from November 2013 through February 2014.

The theme for Autodesk DevDays 2013 is rEvolution – Where Desktop meets the Cloud. Come and learn about upcoming releases of several new web service APIs from Autodesk. You'll see how these new web services extend the power of the desktop: delivering easy collaboration, limitless compute power and big data – and are platforms that can deliver the same to you and your customers. It's an opportunity to learn about a range of '360 based' web service APIs delivering you cloud based platforms for a number of industries – Manufacturing, AEC, Infrastructure and more. And, we will of course also cover what's new in the next releases of our desktop products, e.g. AutoCAD, Revit, Inventor, Civil 3D etc.

Note that material at Developer Days is forward-looking and highly confidential, so ADN membership is required. Maybe you are using ADN Open and forums and would like to attend DevDays? Visit www.autodesk.com/joinadn or send an email to your local ADN representative and let's talk. We like to hear from – and help – interested parties, innovators and companies just getting started.

Autodesk DevDays 2013 World-wide Schedule

Here are the dates for this year’s tour. For a more detailed agenda and to register your interest in attending a specific event, head on over to the registration page.

• 2013-11-07 – DevDay, Beijing, China
• 2013-11-08 – DevLab, Beijing, China
• 2013-11-11 – DevDay, Shanghai, China
• 2013-11-12 – DevLab, Shanghai, China
• 2013-11-13 – DevDay, Seoul, South Korea
• 2013-11-15 – DevDay, Tokyo, Japan
• 2013-11-18 – DevDay, Melbourne, Australia
• 2013-11-19 – DevDay, Osaka, Japan
• 2013-11-20 – DevDay, Singapore, Singapore
• 2013-11-22 – DevDay, Bangalore, India
• 2013-12-02 – ADN Conference, Las Vegas, USA
• 2013-12-03 – DevLab, Las Vegas, USA
• 2013-12-09 – DevDay, Paris, France
• 2013-12-10 – DevDay, Milan, Italy
• 2013-12-11 – DevDay, Farnborough, United Kingdom
• 2013-12-12 – DevDay, Munich, Germany
• 2013-12-13 – DevLab, Munich, Germany
• 2013-12-16 – DevDay, Gothenburg, Sweden
• 2013-12-18 – DevDay, Moscow, Russia
• 2014-02-05 – DevDay, São Paulo, Brazil
• 2014-02-12 – DevDay, Mexico City, Mexico

I will be attending all the events in the USA and Europe,   إن شاء الله   (insha'Allah).

It would be a pleasure to meet you there!

I now to return to my backlog of other issues...

Addendum – ISO 8601 Time and Date Standard

One reader responded to this post and asked:

Question: Do you have your months and days reversed in the dates?

They look a little funny...

Answer: No, I do not.

The dates above are given according to the ISO 8601 time and date standard following these general principles (among others):

• Date and time values are ordered from the most to the least significant: year, month (or week), day, hour, minute, second, and fraction of second. The lexicographical order of the representation thus corresponds to chronological order, except for date representations involving negative years. This allows dates to be naturally sorted by, for example, file systems.
• Each date and time value has a fixed number of digits that must be padded with leading zeros.
• For reduced precision, any number of values may be dropped from any of the date and time representations, but in the order from the least to the most significant...

This date format actually used in daily life in some countries, e.g. all Scaninavian ones, as far as I know.

Response: Please check again. The format you mention is YYYY-MM-DD, whereas you seem to have used YYYY-DD-MM.

Answer: Oops.

The danger of using regular expressions, and not even bothering to ever look at the result :-)

Thank you very much for pointing that out!

Fixed.

Registration Open for Autodesk University 2013

Registration is now open for Autodesk University 2013.

It is easier this year, because you use your Autodesk account (Autodesk ID). If you don’t have one, you can easily create it during registration.

The AU website has been updated to help you find all of the preconference events scheduled for Monday, the classes and hands-on labs that might interest you, and other activities taking place during the conference.

All industry specific activities and class highlights are listed on focused pages for

• Product design & manufacturing,
• AEC, infrastructure, and oil & gas,
• Media & entertainment, and
• Education.

You can save up to $500 by signing up before October 20.

I mentioned my three classes when pointing out the class catalog preview.

I am looking forward to seeing you there.

What I Do, Wall Layers and Open Transactions

One of my tasks today and tonight will be a minimal little contribution to an internal ADN meeting, where I was asked to explain briefly to my colleagues in just a couple of minutes what my job involves and what I have been up to for the last couple of months. Tonight, since we have a session each for the western and eastern hemisphere, and the eastern one will require me to set my alarm for 2:30 tomorrow morning.

I thought I might as well share the result here with you also, to provide a rough idea for all of what my everyday work looks like.

Further down I'll also mention two recent cases, dealing with:

• Determining wall layer materials, areas and volumes
• Determining whether a transaction is open
• The Application IsQuiescent property

What I Do

My spontaneous picture of my work life is that I never do anything at all except dealing with ADN cases and writing The Building Coder blog.

My main motivation is probably solving problems, but maybe even stronger than that an urge to help people in whatever manner possible.

Unfortunately for me, I seem to often find it more helpful just to shuffle information around that I receive from others, rather than performing my own research. I would love to spend more time programming and exploring new issues myself, rather than managing information provided by others.

I have a large number of other interests besides that, such as reading, languages, nature, sports, especially climbing, dancing, 5rhythms and dj-ing.

I also have four grown up kids who have left home by now and are out in the world doing their own things, such as composing their own music.

Job-wise, I recently switched from a Windows computer to a Mac and still enthusiastic about that, busy retraining my fingers and compiling open source software. I am a keyboard user and avoid touching the mouse or using the GUI whenever possible. It will take much longer to train my fingers to all the new shortcuts, but they are starting to adapt. I am overjoyed at having a Unix command console now again, after a couple of decades of cmd.exe.

When I offered to talk, I said that I would only be able to cover 30 seconds, since all I do is handle cases and blog, and that is quickly said.

Of course I also do some work creating presentations and conducting trainings at conferences and events such as AU (2, 3) or DevCamp (2, lab).

Jim suggested I could mention my visit to Australia.

Yes, indeed, I went there and gave a Revit API training, followed by a three-day DevLab. It really was a great learning experience and good fun. Some of the participants were extremely well versed in the Revit product usage, and the importance of knowing the product in depth before embarking on any add-in development plans was strongly reinforced.

In spite of that, I spent a while with one of the participants discussing how to implement a family and a command to toggle the family instance state between two conditions, until we discovered that we could save hundreds of lines of code, family complexity, workflow development and user training by just using the existing functionality already provided by Revit: define two different types for the two states, and let the user switch via the instance properties using standard built-in tools – a very impressive experience, cool.

What I Actually Did

That said, I do indeed spend almost all my time with cases and the blog. In 2012 ADN provided a couple of hands-on classroom trainings. The trend in some highly developed areas of the world seems to be going away from hands-on face-to-face trainings and meetings and moving towards virtual interactions and blogging instead.

So, to answer the question more precisely, I put together some statistics on the time I spent on various tasks in the year 2012 in per cent:

• 44% – ADN cases, special support cases, learning new Revit API features cases, newsletter articles
• 17% – Conferences: Autodesk University, DevCamp, DevDays, webcasts
• 14% – Admin including meetings and participating in trainings
• 13% – Blogging
• 6% – Providing hands-on Revit API training
• 6% – Other stuff, including cloud & mobile, plug-in development, Mac learning and setup

I was a bit surprised by some of these results and find them interesting. Maybe you do too.

The results are rather skewed, actually, since a lot of the work I do for the blog stems from case answering, trainings, and conference preparations, so maybe it would be more realistic to classify something between a fifth and a third of the case, conference and training work as blogging instead.

Basically, the intention of the blog is to eliminate the need for questions via ADN cases and discussion forum threads, and simultaneously the latter feed the former.

You could even go to the extreme of saying teat the blog is a filter for everything I do: if it is useful for the blog and can be shared in public, it is worthwhile doing; if not, not.

Therefore, let's return to the Revit API and present some notes on the two cases I mentioned above.

Determining Wall Layer Materials, Areas and Volumes

I recently started looking at foreign language cases as well as English ones, just for fun. I am very impressed by the advances in automatic translation. Here is a question on wall layers:

Question: 如何获取墙的材质厚度、名称等属性

我想请问下墙分层材料能够获取哪些信息？

我通过PickObject()获得墙（基本墙 外部 带砖与金属立筋龙骨复合墙）的Element， 再通过Element.Materials访问到MaterialSet，遍历得到各个Material信息，可得到墙的各个材质， 再根据Element.GetMaterialArea(Material)、Element.GetMaterialVolume(Material)获得该Material的体积和表面积。 单独墙体利用“体积/表面积”得到该Material的厚度是否正确？ 相交墙、曲面墙的情况呢？ 是否有API可以直接访问到该Material的厚度值？

Simply passing that though Google translate yields the following:

How to get the wall thickness of the material, the name and other attributes?

I would like to ask the next wall of layered materials able to get what information?

I PickObject wall (the wall externally with bricks and metal studs keel composite wall) Element. By Element.Materials access to MaterialSet, traverse various Material available wall material. According Element.GetMaterialArea (Material), Element.GetMaterialVolume (Material) to obtain the volume and surface area of the Material. Separate wall volume / surface area of the Material thickness is correct? Intersecting walls, curved wall? API can directly access to the thickness of the Material value?

Answer: Just as you say, the GetMaterialArea and GetMaterialVolume methods will return the volume and surface area of specific materials used within a wall.

This should work just fine for curved and intersecting walls as well.

You can also traverse the wall compound structure yourself to obtain more detailed information. Here is my very first discussion exploring wall compound layers.

Another exploration of this topic looks at extracting material volumes.

The access to the wall layers has been significantly enhanced since then, by the introduction of the new read-write compound layer structure access in Revit 2012, but the basic principles still apply just the same.

If you need more exact values than those returned by the built-in API methods, you can also split the wall into separate parts for a detailed analysis.

Here is a discussion describing such an approach used to determine the exact corner points of the various layers in the internal structure.

This apparently helped, at least to get started in further exploration of this topic.

Determining Whether a Transaction is Open

The other case was in English right from the start:

Question: My Revit add-in presents a modeless form to my users. How can I check from that context whether any other commands or transactions are open in Revit?

For example, the 'insert doors' command may be active.

If Revit is already waiting for user input, e.g. to insert a door, trying to start a transaction causes an error. It would be useful to be able to check whether a transaction is already in progress.

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

Therefore, I strongly suggest basing anything you do on the ModelessForm_IdlingEvent and ModelessForm_ExternalEvent SDK samples introduced in Revit 2013.

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

Also note that using an external event is often a little bit simpler and more appropriate than using an Idling event handler.

Please look at the implementation of my own tooltip for a more detailed explanation.

Basically, you never, ever, need to check for yourself whether a transaction is open at all.

Why? Because, to check whether a transaction is open, you need to use the Revit API. You cannot use the Revit API, though, unless you are in a valid Revit API context.

Mostly, when you are in a valid Revit API context, it is clear whether or not you can start a new transaction, since it depends to a large extent on the event handler that is currently being called.

Therefore, if your requirement is what I imagine it to be, I would simply suggest that you implement whatever you want to achieve based on the Revit SDK samples mentioned, and you will not need any further checks whether or not you can start a transaction, since it will be obvious: when your Idling event handler or external event Execute method is called, you can do what you like, and at all other times you can do nothing at all

Of course, in addition to being allowed to start a transaction at all, you may also have some restrictions due to read-only project documents etc., that also need to be gracefully dealt with.

Two methods are provided which may help with this: Document.IsModifiable andDocument.IsReadOnly. Look at the Revit API help file RevitAPI.chm for further oinformation on their application and usage.

The Application IsQuiescent Property

In addition to this, the Revit API does provide the Application.IsQuiescent property to check whether the application is quiescent. Unfortiunately, this method is not really useful for anything at all in the API right now.

Firstly, it is not at all related to transactions, thus one cannot make any assumption about starting a new transaction based on this. If any document in the current application is in editing mode or an in-place family is being edited, it returns false. Otherwise, true will be returned. That might correspond pretty well to what you are looking for. In reality, this property is by far not as useful as the two other ones mentioned above.

So, secondly, what it does tell you is whether you are currently in a command or edit mode or not. However, as pointed out above, as an API programmer, you already know that. For example, in your own external command, the method would return False, all the time. Ditto in many events and updaters. On the other hand, it should return True when called from Idling event, which again is obvious.

Just as a background information, this method was implemented in a very early attempt to mimic the AutoCAD API. However, due to significant differences, the quiescent state is not equally important in Revit, and thus the method ends up not actually being used in any Revit code.

Response: Thank you, that helped.

I'm making a 'Content Library' function as a modeless form in Revit. The form is intended to be open beside Revit when users work.

It provides content (RFA families) either by browsing by category or searching on family name, family type name, parameter name or parameter value on each of the family types.

The families are located by default on a website using REST. The database behind the website contains information about the family types, its parameters, and also thumbnails and a DWFX file of the RFA. For users with slow internet connections I made it possible to change provider to connect to content in a local database instead of the online website.

The above worked fine until I implemented SendKey Esc x 2 to cancel insert family in Revit.

When you mentioned the Idling event I looked through my code again and found the 'load family into Revit' function called from outside the Idling event. After moving this call into the Idling event handler all worked fine. :-)

Reload Add-in for Debug Without Restart

We explored and learned a lot of interesting areas during the DevLab at AU on Tuesday last week.

One recurring theme is how to effectively debug an add-in without having to restart Revit and reload the entire model each time a change is made to the source code.

A long, long time back, right in the beginning of the Revit .NET API, it was briefly possible to use the Visual Studio Edit and Continue feature for that. That was obviously an absolutely perfect solution. Alas, those times are past, and unlikely to return. I almost find it hard to believe I am not imagining things.

There are in fact several other known solutions to this problem, which I would classify as follows:

• Stupid: set up the Revit project and Visual Studio debug settings to bring you to the exact required debugging position and context in one F5 'start debugging' click. Every time a code modification is required, simply stop debugging, modify the code, recompile and restart Revit. That is the approach I use myself, since I can get by working in absolutely minimal test models.
• Cool: use an interactive scripting language such as Python or Ruby. In fact, the wish be able to modify the API code interactively without requiring the tedious recompile and reload cycle was one of the main motivating factors in implementing the latter. The use of this functionality is obviously just a side effect of the much larger main advantage of being able to play interactively with the code in complete freedom, since it is interpreted on the fly and no compilation at all is required.
• Effective and laborious: convert the code to be debugged to a macro and use the built-in SharpDevelop IDE. This means that you convert the part of your add-in that your are debugging and modifying to a macro. The rest can be left as a compiled DLL. The two components can communicate with each other. When finished debugging, you move the code out of the macro environment into the external DLL again.
• Efficient: use the AddInManager and attach to process to reload repeatedly, with compile and edit cycles.

I already described all three of the solutions not involving Python and Ruby in an earlier discussion on debugging an add-in without restarting Revit.

Melissa Manalac of S-frame was making such efficient use of the AddInManager approach at the DevLab that I asked her to document it for you once again.

She points out that James LeVieux already summarized the process in his comment on that discussion:

Here are the required steps:

1. Start Revit 2013.
2. Before coding, make sure all processes are detached.
3. After coding, rebuild your solution and attach to the Revit process.
4. In Revit, go to the Add-Ins tab > Add-In Manager and reload the desired add-in DLL.
5. Run desired external command.
6. Repeat steps 2 to 5.

You also need to be aware that the AddInManager requires the external commands it loads to use manual transaction mode. This is no significant restriction, since automatic transaction mode is not recommended anyway.

Here are some screen snapshots to further clarify these steps:

1. Start Revit 2013.

2. Before coding, make sure all processes are detached:

3. After coding, rebuild the add-in solution and attach to Revit process.

Rebuild solution:

Attach to process:

Select the Revit.exe process:

4. In Revit, go to the Add-Ins tab > Add-In Manager and reload the desired add-in DLL.

Launch the Add-in Manager:

Load the add-in DLL:

5. Run the desired external command:

6. Repeat steps 2 to 5 as desired.

Many thanks to Melissa for the detailed up-to-date description!

Source Code Coloriser

As I mentioned quite a while back, I use the Visual Studio CopyToHtml plug-in to copy and paste colour coded C# and VB source code to HTML for my blog posts.

Harri Mattison of Boost Your BIM now pointed out that this utility obviously cannot be used in the built-in Revit SharpDevelop macro environment.

He found this online C# code coloriser tool by Pavel Vladov that is quite nice and can be used instead.

Oh, and I found another one myself, tohtml.com, that supports a huge number of different languages besides C#. Unfortunately, it does not escape all the HTML characters, e.g. '<' remains '<' instead of being converted to '&lt;'.

Extra Transaction or Regeneration Required

Whenever your add-in modifies the model in any way and you wish to query the Revit database, you need to pay careful attention to ensure that you do not retrieve stale or invalid data.

If anything unexpected whatsoever happens, one of the first things to consider is the possible need for a document regeneration or additional separate transactions between steps.

These kinds of issues arise frequently.

I discussed adding an extra transaction to modify beam parameters and add openings to it and to create an opening in a slab.

Sometimes a simple document regeneration is also sufficient, e.g. to set the width of a newly created TextNote.

Here are two more typical examples:

• Extra transaction required after loading tag
• Extra regeneration required to populate materials

Extra Transaction Required After Loading Tag

Here is an issue raised by Max, Maciej Szlek, who already contributed code to help distinguish MEP fitting shapes:

Question: I have a duct system and want to attach my tag to its elements, using the code to set a tag type. I tried something like this:

  doc.LoadFamilySymbol(
    [my_tag_family.rfa],
    [type_name],
    out tagType);

  IndependentTag tag = doc.Create.NewTag(
    doc.ActiveView,
    element,
    true,
    TagMode.TM_ADDBY_CATEGORY,
    TagOrientation.Horizontal,
    XYZ.Zero);

  tag.ChangeTypeId(tagType.Id);

This code works fine in some projects, whereas in others Revit throws an InvalidOperationException saying that there is no tag available in the call to the NewTag method. The behaviour seems to vary between different projects and on different elements.

How can that be?

Answer: Have you tried either regenerating the document or placing the tag symbol loading and the tag creation calls in separate transaction, committed individually?

Response: Problem solved. As it turns out, the Revit project needs to have some suitable tag type loaded before calling NewTag. Your transaction hint was very helpful. My earlier code was not enough as it stands. It actually requires separate transactions to load the tag type and add a new tag if there was no other tag loaded before. I did not previously know what Revit meant by 'there is no tag available'.

Furthermore, I was initially using automatic transaction mode for this command, thinking that would free me from worrying about any transaction handling myself at all. I now learned that the automatic transaction mode does not enclose each action in a separate transaction, but wraps all executed functions in the whole external command into one single one. In this case, such an approach is not usable at all.

Thank you for a very useful API lesson :))

Answer: Yes, I already mentioned that automatic transaction mode is unofficially deprecated, and manual mode is recommended for all cases nowadays. Automatic transaction mode is considered obsolete.

Arnošt Löbel's AU class on Core Frameworks in the Revit API provides more details on this topic.

Many thanks to Max for raising this issue and verifying that the solution works!

Extra Regeneration Required to Populate Materials

One of the issues we took a look at during the DevLab at AU last Tuesday was the list of materials attached to a newly duplicated symbol.

At first glance, it appeared that a duplicated family symbol had zero entries in its list of materials, whereas the original symbols material list was correctly populated.

On further exploration, we discovered that this is another case of retrieving stale data after a model modification.

The behaviour is easily rectified by a call to regenerate the model after the symbol duplication.

Here is the final implementation of the external command implementing to test the issue. It expects a structural steel column to be pre-selected, which is a family instance whose associated symbol has exactly one entry in its materials list. We duplicate the symbol. This requires defining a new name. To simplify repeated testing, we generate a new name by simply appending the clock tick counter to the original one. Directly after the call to Duplicate, the new symbol's material list has zero entries, which makes no sense for this kind of symbol. A call to Regenerate fixes that:

[Transaction( TransactionMode.Manual )]
public class Command : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
    Selection sel = uidoc.Selection;
    FamilyInstance inst = null;
 
    if( 1 == sel.Elements.Size )
    {
      foreach( Element e in sel.Elements )
      {
        inst = e as FamilyInstance;
 
        break;
      }
    }
 
    if( null == inst )
    {
      message = "Please select one "
        + "single structural column";
 
      return Result.Failed;
    }
 
    using( Transaction tx 
      = new Transaction( doc ) )
    {
      tx.Start( "Duplicate Symbol" );
 
      FamilySymbol symbol = inst.Symbol;
 
      string name = symbol.Name 
        + DateTime.Now.Ticks.ToString();
 
      int nMaterialsBefore 
        = symbol.Materials.Size;
 
      symbol = inst.Symbol.Duplicate( name ) 
        as FamilySymbol;
 
      // The model is in a temporary state that does 
      // not make sense. Regenerate to clean this up.
 
      int nMaterialsAfter 
        = symbol.Materials.Size;
 
      doc.Regenerate();
 
      nMaterialsAfter = symbol.Materials.Size;
 
      Debug.Assert( 
        nMaterialsAfter.Equals( nMaterialsBefore ),
        "why does the material get lost, please?" );
 
      tx.Commit();
    }
    return Result.Succeeded;
  }
}

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

AU Classes on Python, UI, Server and Framework APIs

Thursday was another very full and fruitful day at AU. I gave my third and last class, the most exciting one in my eyes, on some UI and integration aspects. I was unable to attend Iffat May's class introducing Python and using it in Revit and Vasari via RevitPythonShell, but I love her material so much I am including it anyway. Adam Nagy presented a class addressing cloud and mobile development and the Revit Server API. Finally, Arnošt Löbel provided a peek behind the scenes and into the depths of the fundamental frameworks underlying the Revit API.

Here they are in chronological order:

1. CP3837-L Scripting with RevitPythonShell in Vasari by Iffat May.
2. CP4107 Let's Face It: New Revit 2013 User Interface API Functionality by Jeremy Tammik.
3. CP3093 My First Cloud/Mobile App with Revit Server by Adam Nagy.
4. CP3426 Core Frameworks in the Revit API by Arnošt Löbel.

I am including the class materials below, for your and my own convenience, and also to ensure that all this juicy stuff really is picked up and returned by Internet search engines.

1. CP3837-L RevitPythonShell in Vasari

Iffat provides an entire introductory tutorial to the Python programming language, and then shows how to apply it to solve a number of useful tasks in Revit and Vasari. She makes use of Daren Thomas' Revit Python shell, originally implemented for Revit 2010, then for Vasari, Revit 2012 and Vasari 2.1, and now available for Revit 2013.

RevitPythonShell introduces interactive scripting ability to Revit and Project Vasari. Designers now have the ability to interactively design and manipulate Revit elements using algorithms and computational logic. The class explores the Python structures, variables, data types, and flow control, and shows how to use them to create scripts to control Revit elements dynamically.

• Handout
• Presentation
• Sample code and models

2. CP4107 Revit 2013 User Interface API

This class takes a deeper look at the new user interface and add-in integration functionality provided by the Autodesk Revit 2013 API. It covers 2013 features including Options dialogue custom extensions using WPF components, subscription to Revit progress bar notifications, embedding and controlling a Revit view inside an add-in dialogue for preview purposes, the new drag and drop API, and the UIView. This class is complementary to and expands on CP3272, a Snapshot of the Revit UI API:

• Document management and View API
• Revit progress bar notifications
• Options dialogue WPF custom extensions
• Embedding and controlling a Revit view
• UIView and Windows coordinates
• Drag and drop

From my point of view, one of the most exciting new features provided by the Revit 2013 UI API is the possibility to correlate between Windows screen device coordinates and Revit model coordinates provided by the UIView class, which I used to examine and implement my own Revit tooltip, which also makes use of the new ReferenceIntersector class and Idling event. This has never previously been possible. Now you can do anything you like using the Windows API and connect that intelligently with the underlying Revit model.

• Handout
• Presentation
• Sample code

3. CP3093 Cloud/Mobile App with Revit Server

This class has two objectives: to introduce you to the Revit Server REST API and to introduce you to cloud and mobile programming.

Autodesk Revit Server is a server-based file storage system that we can use to store Revit files. It has a public API that uses simple HTTP known as REST (or Representational State Transfer). REST is a "style" for designing network applications, and it is used to communicate between the server and a client machine. REST is simple, yet powerful enough. You can use it from anywhere where HTTP programming is available: from a desktop, a mobile device or a server-side application. In this class, we discuss what REST is, using the context of Revit Server.

We then go one step further and show you how to create your own REST service in .NET. We implement it as a notification system in the cloud and demonstrate with an Apple iPad/iPhone application in Apple iOS. At the end of this class, you will be able to:

• Use HTTP requests to interact with a REST API
• Programmatically access and modify data available on Revit Server
• Create basic iOS applications in Xcode
• Create a basic REST service in .NET
• Use Apple Push Notification

Here is the detailed handout document:

• Handout

4. CP3426 Core Frameworks in the Revit API

A good understanding of core frameworks in the Revit API is a prerequisite for developing well behaved Revit add-ins. Among the most important ones, the following frameworks play key roles in most applications:

• External applications, commands, and events
• Transactions phases
• Regeneration and transaction modes
• Updaters and other call-backs
• Scoped objects and element validity

These concepts have been around for many releases, yet there are still facts about them that may not be completely understood. This class summarizes the necessary basics, and also sheds some light on the behaviour that is normally hidden 'under the hood'. Knowledge acquired during this class will help Revit developers to build more efficient, safer, and robust applications.

• Paper
• Presentation

By the time you read this, I will be sitting in the plane heading back to Europe.

Take care, and walk in beauty.

AU Classes on the View, MEP and Link APIs

Wednesday was my first normal and full AU day, after completing the developer conference and DevLab activities. I was able to attend two interesting classes held by Revit API developers Steven Mycynek and Arnošt Löbel, and present my own Revit MEP API one. Here they are in chronological order:

• CP3133 Using the Revit Schedule and View APIs by Steven Mycynek
• CP4108 Revit MEP Programming: All Systems Go by Jeremy Tammik
• CP3455 Managing Revit Links with the Revit API by Arnošt Löbel

I am including the class materials below, both for your and my own convenience, and also to ensure that all this juicy stuff really is picked up and returned by Internet search engines.

Schedule and View APIs

Revit 2013 includes a major expansion of the Schedule and View APIs. This class introduces the API for Schedule and Elevation views as well as many methods and properties that apply to all views. Learn how to create and modify these views to help document and display your Revit model.

• Handout
• Presentation
• Sample code
• Sample models

This class should really resolve all those recurring questions associated with the creation of different views once and for all! Take a special deep look at Steve's multitude of useful utility classes in the sample code.

Revit MEP Programming

This class shows how to work programmatically with Revit MEP models. It provides an overview of the entire Revit MEP API with specific focus on the major enhancements in Revit 2013. The most important 2013 feature is the routing preference functionality. An overview of the available samples is provided. All MEP domains including HVAC, electrical, and plumbing are addressed. It shows how to analyse existing systems and create new MEP models from scratch; covers mechanical and electrical system traversal; display of system hierarchies in a tree view; components such as circuits, ducts, pipes, fittings, connectors, cable trays, and conduits; and automatic calculation and sizing based on room and space requirements.

• Handout
• Presentation
• Sample code

Managing Revit Links

This class explains common pitfalls working with links and how to avoid them. It details the creation of Revit link types and instances, and recommends how to easily check or modify the parameters of links. Material describing ways to inquire for data about the various types of external files, including Revit links, is included. It concludes with an overview of a larger Revit link API application – the eTransmit add-in, which enables users to move an entire package of Revit files while maintaining relationships with all linked files.

• Presentation
• Sample code and models

Implementing a BIM Business Transformation

Unrelated to any direct programming topic, here is a white paper on implementing a BIM business transformation that is of interest to visionaries and decision makers and neatly complements the recently released BIM for Infrastructure one.