The Building Coder

Selecting a Face in a Linked File

Here is a chance to look at an interesting method that we never discussed yet, ConvertToStableRepresentation, and the hidden information that it provides access to. It does what it says, converting a Reference to a stable string representation.

Reference and Stable Representation

A reference provides a possibility to identify a piece of geometry, even though geometry is transient, not persistent, memory only, generated on the fly. Still, we sometimes need to identify a piece of it and remember which piece it was. For instance, to dimension the distance between two parallel walls, we need to identify which wall face we are measuring from. This can be achieved using references.

A stable representation can be used to preserve and restore a reference later in the same Revit session or even in a different session in the same document. The ParseFromStableRepresentation method is used to restore the reference. The representation is based on the internal Revit structure and is not intended to be parsed by anyone else except ParseFromStableRepresentation.

Here is a rather unexpected use of this method and the undocumented internals of the stable string representation:

Face Selection in Linked File

Some Revit API functionality is limited to the current project and will not work for linked files. Currently, this most heavily affects the geometric analysis, and methods like FindReferencesWithContextByDirection and its new optimised and simplified Revit 2013 wrapper class ReferenceIntersector.

Another affected area is the interactive element selection, which led to the following question by Valentin Louzeau:

Question: I'm working on a plugin and asking the user to select a face, but it does not work in linked files. I found something using ObjectType.PointOnElement for selection but it doesn't seem to work for my needs. Is there an easy way to do that or do you already have a solution?

Answer: Nope, sorry, there is no easy way to work on a face in a linked file, and I am not aware of any solution for this.

Response: I found a solution using the method ConvertToStableRepresentation on the Reference class.

This string contains the ref document unique ID, its name, and the ID of the picked element in this document. You can get its position in the ref doc and if you insert origin to origin, the element has the same position in the two documents.

Here is an example of a stable representation for a reference to a picked face on a wall in a linked file:

• "7c25d827-3c9c-4cca-b3a0-dd28ee09a289-0002e3a1:0:RVTLINK/7c25d827-3c9c-4cca-b3a0-dd28ee09a289-0002e3a0:161224:5:SURFACE"

From this, the wall element id "161224" can be extracted.

Here is some code in which I tested making use of this:

[TransactionAttribute( TransactionMode.Manual )]
public class SelectFaceInLinkedFile : IExternalCommand
{
  public Result Execute( 
    ExternalCommandData commandData, 
    ref string message, 
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
 
    PlanarFace Plan = SelectFace( uiapp );
 
    return Result.Succeeded;
  }
 
  public static PlanarFace SelectFace( 
    UIApplication uiapp )
  {
    Document doc = uiapp.ActiveUIDocument.Document;
 
    // get all ref doc. 
 
    IEnumerable<Document> doc2 
      = GetLinkedDocuments( doc );
 
    // get the ref of a selected plane
 
    Selection sel = uiapp.ActiveUIDocument.Selection;
 
    Reference pickedRef = sel.PickObject( 
      ObjectType.PointOnElement, 
      "Please select a Face" );
 
    Element elem = doc.GetElement( 
      pickedRef.ElementId );
 
    // get the true position picked 
    // in the active document
 
    XYZ pos = pickedRef.GlobalPoint;
 
    // get the ID of the element containing the 
    // face you picked in the active document 
    // and in its host document
 
    string s = pickedRef
      .ConvertToStableRepresentation( doc );
 
    string[] tab_str = s.Split( ':' );
 
    string id = tab_str[tab_str.Length - 3];
 
    int ID;
    Int32.TryParse( id, out ID );
 
    Type et = elem.GetType();
 
    if( typeof( RevitLinkType ) == et
      || typeof( RevitLinkInstance ) == et
      || typeof( Instance ) == et )
    {
      foreach( Document d in doc2 )
      {
        if( elem.Name.Contains( d.Title ) )
        {
          Element element = d.GetElement( 
            new ElementId( ID ) );
 
          Options ops = new Options();
          ops.ComputeReferences = true;
 
          // write the name of the element and the 
          // number of solids in this only for 
          // control to show the possibilities
 
          MessageBox.Show( element.Name, 
            element.get_Geometry( ops )
              .Objects.Size.ToString() );
 
          GeometryObject obj 
            = element.get_Geometry( ops )
              .Objects.get_Item( 0 );
 
          // test all surfaces of solids in the 
          // element and return the one containing 
          // the picked point as a planarface to 
          // build my sketchplan
 
          foreach( GeometryObject obj2 in 
            element.get_Geometry( ops ).Objects )
          {
            if( obj2.GetType() == typeof( Solid ) )
            {
              Solid solid2 = obj2 as Solid;
              foreach( Face face2 in solid2.Faces )
              {
                try
                {
                  if( face2.Project( pos )
                    .XYZPoint.DistanceTo( pos ) == 0 )
                  {
                    return face2 as PlanarFace;
                  }
                }
                catch( NullReferenceException )
                {
                }
              }
            }
          }
        }
      }
    }
    return null;
  }
 
  // this part is not mine, i found it on the internet, 
  // i don't anderstand all the code
 
  public static IEnumerable<ExternalFileReference> 
    GetLinkedFileReferences( Document _document )
  {
    var collector = new FilteredElementCollector( 
      _document );
 
    var linkedElements = collector
      .OfClass( typeof( RevitLinkType ) )
      .Select( x => x.GetExternalFileReference() )
      .ToList();
 
    return linkedElements;
  }
 
  public static IEnumerable<Document> 
    GetLinkedDocuments( Document _document )
  {
    var linkedfiles = GetLinkedFileReferences( 
      _document );
 
    var linkedFileNames = linkedfiles
      .Select( x => ModelPathUtils
        .ConvertModelPathToUserVisiblePath( 
          x.GetAbsolutePath() ) ).ToList();
 
    return _document.Application.Documents
      .Cast<Document>()
      .Where( doc => linkedFileNames.Any( 
        fileName => doc.PathName.Equals( fileName ) ) );
  }
}

Here is SelectFaceInLinkedFile.zip containing Valentin's sample code and Visual Studio solution.

Many thanks to Valentin for the novel use of this method and its undocumented embedded information.

This is obviously all undocumented internal stuff that is not guaranteed to work at all in any way, and actually is guaranteed to change at some point in the future (as everything must change) with no prior warning whatsoever, so use at your own risk or just ponder and enjoy.

DevBlog, DevCamp, Element and Project Wide Data

Every once in a while, I like to start the week with a bang, so here goes, with a risk of information overload on the following topics:

• ADN AEC DevBlog
• Autodesk AEC DevCamp
• Goodbye Kailash Kute
• Project Wide Data Storage
• DataStorage Element
  • Simple DataStorage Sample
  • Identifying DataStorage Elements

ADN AEC DevBlog

I bet you are not half as confused as we always are internally about DevDays, DevLabs, DevNotes, and last but not least DevCamps.

I recently mentioned that we are raising the bar one further with the introduction of the Autodesk Developer Network ADN DevBlogs, for AutoCAD and Infrastructure, marking the advent of a whole series and a significant shift from material available to ADN members, like technical solutions known as DevNotes on the ADN extranet, to material publicly available to everyone. Following these two, we are now proud to present the AEC DevBlog!

The AEC DevBlog covers Revit, Navisworks and other Autodesk AEC and BIM technologies and their APIs.

Here are links to the three DevBlogs live so far:

• AutoCAD DevBlog
• Infrastructure Modelling DevBlog
• AEC DevBlog

ADN DevBlogs for Manufacturing, Media & Entertainment are also expected.

For more information, please refer to Stephen Preston's welcome post.

Only a month to go – Autodesk AEC DevCamp

I also recently mentioned the upcoming AEC DevCamp conference being held in Boston June 6-7, where customers, resellers and professional developers come together and learn about extending Autodesk technologies through software development.

The AEC DevCamp comprises several parallel tracks for

• Revit App Development for Beginners and Intermediates
• Revit App Development for Intermediates and Experts
• Infrastructure Technologies
• Cloud/Mobile Technologies
• Other Autodesk AEC Technologies
• Business

The classes are presented by a managers, core developers, ADN experts and others and cover all levels from people just beginning to do software development with our technologies to experts looking to build sophisticated cloud and mobile apps. You can also grab a chance to meet and talk with these interesting and influential people.

Besides welcoming new beginners to the Revit API, I would also like to bid farewell to an old-timer:

Goodbye Kailash Kute

I gratefully acknowledge this very sweet parting message from one of our most prolific commenters and autonomous Revit MPE API problem solvers, Kailash Kute:

Dear Jeremy, i would like to inform you that since i have changed my current company to another where there is no Revit, but till this whole time which i used to blog post on building coder, was very good and fantastic journey, your blog was most useful stuff for me, i liked the coding, the posts, the information provided on this. i will miss but i also like to appreciate the work you are doing for revit stuff. Really it was a wonderful journey till this day on BuildingCoder.

Very many thanks, Kailash, for your numerous contributions and great endurance in solving so many Revit MEP API issues!

I was always sorry not to be able to help you more, and very impressed that you struggled on and succeeded in solving every single issue in the end.

Funnily enough, I just last week published an updated pipe cap creation post superseding the original one on which you submitted all your comments :-)

I wish you much success and all the best in your new role!

So long, and thanks for all the fish!

Back to the nuts and bolts of the Revit API, here is a case brought up and eventually solved by Mario Guttman of Perkins+Will:

Project Wide Data Storage

Here is a simple question that has been asked repeatedly, so I guess it is worthwhile pointing out:

Question: Is it possible to save some data in the Revit model that has no relation to any specific Revit model building element?

For instance, in AutoCAD I can store data in the named objects dictionary, and I can store xdata or xrecord to be saved with an entity.

I know that it is possible to store extensible storage data on individual Revit elements, but I need a place to save data applying to the entire model.

How can I achieve this, please?

Answer: Although extensible storage is indeed associated with individual elements, you can easily store global data in certain singleton elements.

There are several such elements that are always guaranteed to exist, and to exist only once, so-called singleton instances. One such instance is the ProjectInformation element, whose category is OST_ProjectInformation.

It was commonly used to store global shared parameters in the past, and the same of course applies for extensible storage as well:

• Define a new parameter
• Store project data
• Add a category to a parameter binding

In another case, an arbitrary element was required to format a parameter value, and the ProjectInformation singleton was used for that also.

For complete background information on extensible storage in Revit 2012, I would suggest looking at my Autodesk University 2011 class and lab on this topic, which tell the complete story. I recently published the handouts and sample material for those here on the blog to provide more immediate access.

DataStorage Element

Better still for your case, one of the add-in integration features introduced by the Revit 2013 API is a new DataStorage element to enable add-ins to store extensible storage data completely independently of all BIM database elements.

The DataStorage element is only accessible through the API, not through the user interface. Here is the excerpt on it from the 'What's New' section of the Revit Quasar SDK help file RevitAPI.chm:

The new DataStorage class represents an element which API applications can create logically organize different sets of ExtensibleStorage entities into separate elements. This allows an application to update one set of data in a local workshared project without locking other elements.

To demonstrate the usage of the new DataStorage element, here is a very nice set of samples by Victor Chekalin, Виктор Чекалин.

Simple DataStorage Sample

Storing data in a DataStorage element is very easy.

You can follow these steps to write your own data to a DataStorage element:

1. Create a new DataStorage using static method Create of DataStorage class.
2. Create a Schema.
3. Create an Entity which contains data you want to save.
4. Set entity to the created DataStorage.

To read data from DataStorage you need to:

1. Find DataStorage in the project (using FilteredElementCollector).
2. Get the entity from the retrieved DataStorage.
3. Read data from the Entity.

For example, assume we need to store in each document when a document was created and by whom.

On DocumentCreated event write information about the creating user:

  using( Transaction t = new Transaction( 
    doc, "Create created info" ) )
  {
    t.Start();
 
    // Create data storage in new document
 
    DataStorage createdInfoStorage 
      = DataStorage.Create( doc );
 
    // Create entity which store created info
 
    Entity entity = new Entity( 
      CreatedInfoSchema.GetSchema() );
 
    entity.Set( "CreatedUser", 
      Environment.UserName );
 
    entity.Set( "CreatedDate", 
      DateTime.Now.ToString() );
 
    // Set entity to the data storage element
 
    createdInfoStorage.SetEntity( entity );
 
    t.Commit();
  }

And read information later:

  // Retrieve data storage
 
  FilteredElementCollector collector =
      new FilteredElementCollector( doc );
 
  var dataStorage =
      collector
      .OfClass( typeof( DataStorage ) )
      .FirstElement();
 
  if( dataStorage == null )
  {
    message = "No data storage found "
      + "in current project";
 
    return Result.Failed;
  }
 
  // Retrieve entity from the data storage
 
  Entity createdInfoEntity = dataStorage.GetEntity( 
    CreatedInfoSchema.GetSchema() );
 
  if( !createdInfoEntity.IsValid() )
  {
    message = "Data storage doesn't "
      + "have CreatedInfoSchema";
 
    return Result.Failed;
  }
 
  var createdUser = createdInfoEntity.Get<string>( 
    "CreatedUser" );
 
  var createdDate = createdInfoEntity.Get<string>( 
    "CreatedDate" );
 
  StringBuilder sb = new StringBuilder();
 
  sb.AppendFormat( "Created user: {0}\r\n", 
    createdUser );
 
  sb.AppendFormat( "Created date: {0}", 
    createdDate );
 
  TaskDialog.Show( "Project created info", 
    sb.ToString() );

Identifying DataStorage Elements

The simple DataStorage example above very simple indeed. It has one big disadvantage, though: In a project there could be a lot of DataStorage elements including elements created by other developers. So, we must implement a method to differentiate one DataStorage from another and retrieve only the DataStorage elements we really need.

The simplest way to achieve this is to search for a singleton DataStorage element of the expected Schema.

Let’s look at another example in which we store our own settings for the entire project which we could use in our add-in.

At first, create a Settings class

  public class MyProjectSettings
  {
    public int Parameter1 { get; set; }
    public string Parameter2 { get; set; }
  }

Next, create a schema for it:

  public static class MyProjectSettingsSchema
  {
    readonly static Guid schemaGuid = new Guid( 
      "{9DBE0174-AA01-4CDD-BA86-96DE1FDCE041}" );
 
    public static Schema GetSchema()
    {
      Schema schema = Schema.Lookup( schemaGuid );
 
      if( schema != null ) return schema;
 
      SchemaBuilder schemaBuilder =
          new SchemaBuilder( schemaGuid );
 
      schemaBuilder.SetSchemaName( 
        "MyProjectSettings" );
 
      schemaBuilder.AddSimpleField( 
        "Parameter1", typeof( int ) );
 
      schemaBuilder.AddSimpleField( 
        "Parameter2", typeof( string ) );
 
      return schemaBuilder.Finish();
    }
  }

For reading and writing settings to the DataStorage, we can implement a class like the following MyProjectSettingStorage:

class MyProjectSettingStorage
{
  readonly Guid settingDsId = new Guid(
    "{A71F620F-BD0D-46DD-AECD-AFDEF0DFFD74}" );
 
  public MyProjectSettings ReadSettings(
    Document doc )
  {
    var settingsEntity = GetSettingsEntity( doc );
 
    if( settingsEntity == null
      || !settingsEntity.IsValid() )
    {
      return null;
    }
 
    MyProjectSettings settings =
        new MyProjectSettings();
 
    settings.Parameter1 = settingsEntity.Get<int>(
      "Parameter1" );
 
    settings.Parameter2 = settingsEntity.Get<string>(
      "Parameter2" );
 
    return settings;
  }
 
  public void WriteSettings(
    Document doc,
    MyProjectSettings settings )
  {
    var settingDs = GetSettingsDataStorage(
      doc );
 
    if( settingDs == null )
    {
      settingDs = DataStorage.Create( doc );
    }
 
    Entity settingsEntity = new Entity(
      MyProjectSettingsSchema.GetSchema() );
 
    settingsEntity.Set( "Parameter1",
      settings.Parameter1 );
 
    settingsEntity.Set( "Parameter2",
      settings.Parameter2 );
 
    // Identify settings data storage
 
    Entity idEntity = new Entity(
      DataStorageUniqueIdSchema.GetSchema() );
 
    idEntity.Set( "Id", settingDsId );
 
    settingDs.SetEntity( idEntity );
    settingDs.SetEntity( settingsEntity );
  }
 
  private Entity GetSettingsEntity(
    Document doc )
  {
    FilteredElementCollector collector =
        new FilteredElementCollector( doc );
 
    var dataStorages =
        collector.OfClass( typeof( DataStorage ) );
 
    // Find setting data storage
 
    foreach( DataStorage dataStorage in dataStorages )
    {
      Entity settingEntity =
        dataStorage.GetEntity( MyProjectSettingsSchema.GetSchema() );
 
      // If a DataStorage contains 
      // setting entity, we found it
 
      if( !settingEntity.IsValid() ) continue;
 
      return settingEntity;
    }
 
    return null;
  }
}

Remember, the DataStorage element storing project-wide settings must be a singleton. So, before writing settings we look for an existing DataStorage and if it doesn’t exist, create it. For searching, we check each data storage element for the Setting entity.

Of course, you could also use another way to differentiate one DataStorage element from another. For example, by creating an auxiliary identification schema and attaching an entity instance of it to each DataStorage element. Using this entity, you can check whether a given DataStorage element is the one we need or not when retrieving it. You might also be able to make use of the built-in Revit API Element.UniqueId property, or other means of identification. It depends on your tasks.

Here is DataStorageSample.zip containing the full Visual Studio solution, project files, source code, and add-in manifests for Victor's two DataStorage samples.

Many thanks to Victor for providing and documenting this, providing such an easy entry point for everybody!

Create a Pipe Cap

Happily mixing the different Revit versions, let me follow up my work on the Revit MEP 2013 API and the updated AdnRme sample by another MEP related topic.

Before getting to that, though, here is a brief heads-up for a new technology preview on Autodesk Labs:

BIM Coordinator

The effective organization of project data in shared or related coordinates is essential to effective collaboration across disciplines and good quality project information. BIM Coordinator for AutoCAD Civil 3D and Revit is a technology preview that assists project team members with building and site grids.

Here is a brief overview taken from the labs:

Building grids are generally selected based on the layout and shape of the building, usually using the lower left corner of the selected orientation as a reference point. Building grids are established by the lead designer of a project for use by all members of the building design team. This grid ensures that different disciplines' building designs use the same reference for purposes of building analyses, drawing production, and other tasks requiring coordinated building data.

Site grids are generally based on Northing and Easting coordinates. They are usually established for a region; although arbitrary grids can be established for a single project or site. For example, in the UK most sites are related to the Ordinance Survey (OS) grid. Site elevations (levels) are also based on an OS benchmark or other site/project benchmark.

BIM Coordinator automates the more error-prone manual steps in the coordination of site and building grids between the AutoCAD and Revit environments, currently for the 2012 versions. The tool specifies one common XYZ point and its orientation in the XY plane between the two coordinate systems. This reference point defines the relationship between the building and site grid.

Miroslav Schonauer will be explaining some background and sharing source code from this utility at the upcoming AEC DevCamp in Waltham June 6-7.

Create a Pipe Cap

Back to the Revit MEP API, I presented an example to create a pipe cap in Revit 2011 over a year ago.

Now Mick Kulik of Hydratec, Inc. discovered that the existing sample code did not work in his case, and worked together with Saikat Bhattacharya at the AutoCAD DevLab in San Rafael to fix this issue for Revit 2012.

Here is the original problem and its solution:

Question: Following the post about creating a pipe cap, I was not able to get a cap to connect to a pipe in Revit MEP 2012. The Error is "Line is too short". Is there a new way to connect caps to pipes in Revit MEP 2012?

Answer: Saikat came down to give us a hand last week at the AutoCAD DevLab in San Rafael. He had some sample code to attach caps to sloping pipes. I was able to massage his code to fit our needs, and have attached his CapAtStartOfPipe.zip containing the entire source code and Visual Studio solution implementing this command.

Saikat's code worked on all the cases we tested except when trying to connect the cap to a non-sloped vertical pipe, so I built in a case to handle it which worked for my test cases:

  // rotate the cap if necessary
 
  // rotate about Z first

  XYZ pipeHorizontalDirection 
    = new XYZ( dir.X, dir.Y, 0.0 ).Normalize();
 
  ConnectorSet c2 
    = fi.MEPModel.ConnectorManager.Connectors;
 
  Connector capConnector = null;
 
  foreach( Connector c in c2 )
  { 
    capConnector = c; 
  }
 
  XYZ connectorDirection 
    = -capConnector.CoordinateSystem.BasisZ;
 
  double zRotationAngle 
    = pipeHorizontalDirection.AngleTo( 
      connectorDirection );
 
  Transform trf = Transform.get_Rotation( 
    start, XYZ.BasisZ, zRotationAngle );
 
  XYZ testRotation = trf.OfVector( 
    connectorDirection ).Normalize();
 
  if( Math.Abs( testRotation.DotProduct( 
    pipeHorizontalDirection ) - 1 ) > 0.00001 )
  {
    zRotationAngle = -zRotationAngle;
  }
 
  Line axis = doc.Application.Create.NewLineBound( 
    start, start + XYZ.BasisZ );
 
  ElementTransformUtils.RotateElement( 
    doc, fi.Id, axis, zRotationAngle );
 
  // Need to rotate vertically?
 
  if( Math.Abs( dir.DotProduct( XYZ.BasisZ ) ) 
    > 0.000001 )
  {
    // if pipe is straight up and down, 
    // kludge it my way else
 
    if( dir.X == 0 && dir.Y == 0 && dir.Z != 0 )
    {
      XYZ yaxis = new XYZ( 0.0, 1.0, 0.0 );
 
      double rotationAngle = dir.AngleTo( yaxis );
 
      if( dir.Z == 1 )
      {
        rotationAngle = -rotationAngle;
      }
 
      axis = doc.Application.Create.NewLine( 
        start, yaxis, false );
 
      ElementTransformUtils.RotateElement( 
        doc, fi.Id, axis, rotationAngle );
    }
    else
    {
      #region sloped pipes
 
      double rotationAngle = dir.AngleTo( 
        pipeHorizontalDirection );
 
      XYZ normal = pipeHorizontalDirection
        .CrossProduct( XYZ.BasisZ );
 
      trf = Transform.get_Rotation( 
        start, normal, rotationAngle );
 
      testRotation = trf.OfVector( dir ).Normalize();
 
      if( Math.Abs( testRotation.DotProduct( 
        pipeHorizontalDirection ) - 1 ) < 0.00001 )
      {
        rotationAngle = -rotationAngle;
      }
 
      axis = doc.Application.Create.NewLineBound( 
        start, start + normal );
 
      ElementTransformUtils.RotateElement( 
        doc, fi.Id, axis, rotationAngle );
 
      #endregion
    }
  }
 
  doc.Regenerate();
 
  // pick connector on cap:
 
  ConnectorSet connectors 
    = fi.MEPModel.ConnectorManager.Connectors;
 
  Debug.Assert( 1 == connectors.Size, 
    "expected only one connector on pipe cap element" );
 
  Connector cap_end = null;
 
  foreach( Connector c in connectors )
  { 
    cap_end = c; 
  }
 
  // pick closest connector on pipe:
 
  connectors = pipe.ConnectorManager.Connectors;
 
  Connector pipe_end = null;
  double dist = double.MaxValue;
  foreach( Connector c in connectors )
  {
    XYZ p = c.Origin;
    double d = p.DistanceTo( start );
    if( d < dist )
    {
      dist = d;
      pipe_end = c;
    }
  }
  pipe_end.ConnectTo( cap_end );
 
  doc.Regenerate();
 
  // After ConnectTo, the cap size is double, so 
  // need to change the nominal radius to half.
 
  if( fi != null )
  {
    ConnectorSet pipeConnectors 
      = pipe.ConnectorManager.Connectors;
 
    Connector pipeEnd = null;
 
    foreach( Connector c in pipeConnectors )
    {
      pipeEnd = c;
    }
    double radius = pipeEnd.Radius;
 
    Parameter para = fi.get_Parameter( 
      "Nominal Radius" );
 
    if( para != null && !para.IsReadOnly )
    {
      para.Set( radius );
    }
  }

Here is a screen capture of the result of testing caps on a vertical pipe:

Many thanks to Saikat and Mick for providing this new sample!

The ADN MEP Sample AdnRme for Revit MEP 2013

Yesterday I discussed the Revit 2013 MEP API and the external services framework.

In preparation for my Revit MEP API presentation at the upcoming AEC DevCamp in Boston in June, I also migrated the ADN MEP API sample AdnRme to Revit MEP 2013.

The initial flat migration was extremely straightforward with zero code changes required.

I obviously had to change the Revit API assembly references, which forces an update of the .NET framework version to 4.0. After bumping the framework version, the whole solution immediately compiled with zero errors and warnings. I must admit I was a bit surprised.

New One-box Product Type

On loading it, though, I was surprised again, because the add-in ribbon panel was simply not displayed.

Debugging the external application OnStartup method revealed that since I was running and testing it in a one-box flavour of Revit, the product type was not 'MEP' but simply 'Revit'. To fix this, I had to add support for both of those enumeration values to my product type test:

public Result OnStartup( UIControlledApplication a )
{
  // only create a new ribbon panel in Revit MEP:
 
  ProductType pt = a.ControlledApplication.Product;
 
  //if( ProductType.MEP == pt ) // 2012
 
  if( ProductType.MEP == pt 
    || ProductType.Revit == pt ) // 2013
  {
    AddRibbonPanel( a );
    return Result.Succeeded;
  }
  return Result.Cancelled;
}

With that little change in place, everything works fine and my ribbon panel shows up as expected:

Actually, for full-fledged support of the new runtime discipline switching, I could add more flexible enabling and disabling of my buttons, if I wanted to, for instance by dynamically hiding this application when the MEP discipline is not enabled.

Here is the 'About' box, automatically populated with properties harvested from the .NET assembly company, copyright, description, product, title and version and attributes, explaining briefly what this sample is about:

History and Functionality

By the way, although I have been demonstrating and using this sample for many years now, I have still not described its functionality in detail here in the blog, so maybe that is something I should do right now.

Several descriptions have been made publicly available in the past, though, for instance in the materials for my Autodesk University 2011 virtual class CP4453 Everything in Place with Autodesk Revit MEP Programming, covering both the Revit MEP 2012 API features and the Revit MEP API in general.

Before that, I already published the code here on the blog for Revit MEP 2012 and previous versions, and at previous Autodesk University and AEC DevCamp events.

The AdnRme sample demonstrates several Revit MEP API aspects, in two separate main areas:

• HVAC air terminal analysis and sizing.
• Hierarchical display of an electrical system.

It also demonstrates some Revit and .NET API aspects not directly related to the MEP API, such as:

• External application implementation.
• About box, automatically populated using .NET assembly properties.
• Progress bar.

AdnRme implements an external application to define a custom user interface to access the sample commands, as you can see from the ribbon panel shown above. The about box is also shown above.

The progress bar may be useful in a large project, since the processing of a large number of elements may take a noticeable amount of time, and is implemented using a standard .NET modeless form:

HVAC Air Terminal Analysis and Sizing Sample

The HVAC part of the MEP sample was originally implemented based on Revit 2008, before the advent of any MEP-specific API at all, using pure generic Revit element and parameter access to analyse and modify the HVAC duct system.

It supports a typical HVAC engineering workflow including the following tasks:

• Placement and sizing of air distribution ducts and terminals.
• Analysis and verification of results.

In a little more detail, the workflow might look like this:

• Manually lay out air terminals.
• Run heating and cooling load analysis.
• Based on load analysis, assign flow to terminals.
• Based on terminal flow, size air terminals.
• Validate design; a common check figure uses air flow per surface area.

The MEP HVAC sample was originally implemented for Revit 2008 and based on room elements, since spaces had not yet been introduced back then. It was modified for RME 2009 to use spaces.

It implements the following four commands to support the HVAC engineering workflow described above. The first three support the actual workflow itself, the fourth cleans up and resets the data manipulated by them:

• Assign flow to terminals.
• Change air terminal size.
• Calculate and display flow density as colour fill to verify design by air flow per surface area.
• Reset demo.

This workflow is exercised in the following simple office building sample model with a place holder duct system in place:

Here it is in plan view:

The progress of the steps is displayed by four schedules set up in the sample model:

Initially, all the 51 diffusers are the same:

The 33 spaces have calculated and specified supply air flows defined, but no actual flow:

The CFM per SF parameter in the right-hand column is defined to generate a colour schema at the end to verify the results visually at a glance, and is currently still set to zero.

The air terminals have not yet been properly analysed and sized:

Their flow and actual supply air flow is still zero:

Executing the commands in the proper sequence fixes all this:

• Assign flow to terminals: calculate the required flow per terminal by dividing the required flow for the space by the number of terminals, and assigning the resulting value to each terminal via its Flow parameter.
• Change air terminal size: for each diffuser type, determine its minimum and maximum flow. Select the type that ensures that the actual flow lies between these two.
• Calculate and display flow density as colour fill to verify design by air flow per surface area: calculate the CFM per SF using the built-in parameters ROOM_ACTUAL_SUPPLY_AIRFLOW_PARAM and ROOM_AREA and set the "CFM per SF" parameter accordingly.

The schedules are all updated, and the predefined colour fill displays and enables visual verification of the results:

Electrical Hierarchy Sample

Later during the lifetime of this sample, the electrical hierarchy functionality was added, initially based on non-MEP-specific analysis of parameter values to determine the system structure, later rewritten and significantly simplified by accessing the MEP connectors for this task instead.

In a way, the electrical hierarchy part is closely related to the TraverseSystem duct system SDK sample, which traverses a duct system by moving through its elements from predecessor to successor element through the connectors and storing the resulting tree data in an HTML file.

The AdnRme electrical sample does the same and displays the result in a tree view form instead:

It actually determines and displays the hierarchical structure of the electrical systems in the model in several different ways. Its focus is to:

• Traverse the electrical system
• Reproduce the system browser data structure in a tree view
• Determine and display the complete connection hierarchy in a tree view

The standard RME system browser displays electrical components in a three-level flat list, and the complete hierarchical structure of the connection tree is not immediately apparent. This sample inspects the electrical systems and reproduces the structure and information displayed by the system browser as well as the full connection hierarchy. It implements the following commands:

• CmdElectricalConnectors
• CmdElectricalSystemBrowser
• CmdUnhostedElements

The first two analyse the electrical system hierarchical structure and present it to the user in a tree view in a modeless dialogue, either in the full hierarchical structure, or in the three-tier structure used by the system browser; the third detects and lists un-hosted elements.

The form displaying the full electrical system hierarchical structure is shown above. Besides the hierarchical structure, it also presents a list of panels and devices on the left-hand side and highlights them in bold in the hierarchical tree display.

Clicking on a panel node in the left-hand list redisplays the tree on the right, with all the tree nodes except the selected panel or device collapsed. Here we select the panel H-2:

Here, transformer T1 is selected instead:

Being modeless, the form remains visible and can be navigated after the command has terminated. You can leave the form open and switch back and forth between it and Revit to explore the electrical system simultaneously from both points of view. Note, however, that updates to the model will not be reflected in the dialogue until the command is re-executed. A sample model elec_project.rvt is provided. Also note that this was originally implemented a long time ago and does not take all of Arnošt's recent advice on interaction with a modeless dialogue and avoiding too much use of the Idling event into account. On the other hand, the modeless form never attempts to make any use whatsoever of the Revit API, so there should be nothing to worry about in this case.

Besides the connection hierarchy tree, the electrical sample also implements these other commands:

• Obsolete pre-connector approach
• Three-tier system browser structure
• Find un-hosted elements

The obsolete pre-connector parameter-based approach is still included in the source code, in the C# module CmdElectricalHierarchy2.cs, but has been removed from the user interface.

The system browser three-tier structure is also displayed in a tree structure, like this:

The un-hosted element command simply displays a Windows message box listing all elements, which may well overflow the screen in a large untidy model:

As said, I documented some other aspects of this sample in the last few years' Revit MEP API classes at Autodesk University and the AEC DevCamp two years back, so if you really want to know still more, you might be lucky there. I think this just about covers it, though, actually more than enough.

Here is adn_rme_2013.zip containing the full Visual Studio solution, source code, add-in manifest and electrical and HVAC sample models to run this and play with. Enjoy.

Many thanks once again to Martin Schmid for motivating and helping me set up the HVAC sample back then, many years ago, and many other inspiring impulses since!

US Army Corps of Engineers Revit Templates

Here is a little piece of news that just happened to come past my way and might be of interest to you as well, even though it is not API related:

The US Army Corps of Engineers ASACE has released version 1 of their Revit Architecture, Structure, MEP templates.

These templates were developed to standardize MILCON production documentation and deliverables created by in-house USACE staff to reduce project start-up and configuration lead times, improve the quality and consistency of the contract deliverables and increase the adoption of BIM in general.

If you are interested in this fiscal year's opportunities with USACE, here are some interesting links:

• Federal Business Opportunities
• Federal procurement bidding opportunity search
• USACE FY12 Acquisition Forecast – Military Construction

The Revit 2013 MEP API and External Services

I mentioned a few MEP-specific enhancements in the Revit 2013 API. To recap, the enhancements include:

• Access to routing preferences, selection of pipe sizes, materials, fitting types, and the RoutingPreferenceTools SDK sample demonstrating its use
• Pipe and duct friction factors
• MEPSection base class for duct and pipe sections
• Viscosity and density at specified temperatures, new FluidType and enhanced FluidTemperature classes
• Read and write access to panel schedule spare circuit values
• Access to localized user-visible display strings for enumeration values via new LabelUtils.GetLabelFor overloads
• ConnectorProfileType and PartType enumeration changes
• ConnectorElement changes in the family environment, and new static creation methods replacing the obsolete ones on the FamilyItemFactory class.
• A new ThermalProperties class, thermal material assets, thermal information in gbXML
• New calculation functionality and the external services framework
• MEP piping, system routing and centre line functionality
• A new Light and Light Group API
• ReferenceIntersector class

For more information on these and many other Revit API enhancements, please refer to the What's New section of the Revit API help file RevitAPI.chm.

Here are some additional notes on the external services framework:

External Services Framework

The new External Services framework wraps external service functionality, enabling certain services such as analysis or calculations to be encapsulated and replaced, providing a basis for future MEP calculations and structural code checking. The following excerpt from the Revit API help file RevitAPI.chm description of the new ExternalService class provides a pretty good idea of its use:

This is a base class from which SingleServerService and MultiServerService classes are inherited. It implements all basic methods, and the inherited classes add more specific methods. Use this base class to get information about a service and its servers, and the inherited classes to set or get active servers. Functionality:

• Add and remove a server to and from a service
• Query information about a service
• Access servers currently registered for a service
• Get and set active server (or servers) for a service

Although the framework is in place and fully functional in Revit 2013, no in-house external services making use of external servers have yet been implemented. For this reason, no examples of this framework have yet been provided.

The next thing I intend to do regarding Revit MEP is migrate my trusty old AdnRme sample and MEP sample code for Revit 2012 to Revit 2013.

The Schedule API and Access to Schedule Data

Somehow I seem to be spending the vast majority of my time just shovelling information back and forth, preparing for conferences and trainings and answering questions. It is always a great pleasure for me to actually get in a teeny weenie bit of programming in between, so I am happy that I managed to find time to create the new little sample application described below.

One of the many exciting enhancements in the Revit 2013 API is the new Schedule API. Here is the description from the Revit API help file RevitAPI.chm What's New section:

Schedule API

Several new classes have been added to allow schedule views to be created, modified, and added to drawing sheets. Major new classes include:

• The ViewSchedule class that represents the schedule view. Its create methods are used to create new schedules.
• The ScheduleField class for the individual fields in a schedule.
• The ScheduleSheetInstance class represents schedules placed on sheets. The create method creates an instance of a schedule on a sheet.
• The ScheduleDefinition class defines the contents of a schedule view, including:
  1. Basic properties that determine the kind of schedule, such as the schedule's category.
  2. A set of fields that become the columns of the schedule.
  3. Filters that restrict the set of elements visible in the schedule.
  4. Sorting and grouping criteria.

Running API commands in Schedule Views

API commands may now be active when a Schedule is active in the current document.

Schedule export

The ViewSchedule class has been added to the API and the method ViewSchedule.Export method exports an existing schedule to a text file.

As I already mentioned, the ability to create a schedule is demonstrated by the ScheduleCreation SDK sample.

Before even dreaming of creating new schedules, however, many people are interested in simply accessing the data in existing ones.

Accessing Schedule Data

Fitting in nicely with this, a couple of queries recently came in on accessing schedule data.

The Revit API currently does not provide a method to access and cycle through the schedule data directly.

The new Revit 2013 schedule export functionality described above provides for a very simple workaround, however: you can use the ViewSchedule.Export method to export the schedule data to a text file, and then parse the resulting file to access the data.

The ViewSchedule.Export method takes a ViewScheduleExportOptions argument which provides the following properties to enable specification of various text file output settings:

• ColumnHeaders: how to export column headers. Default is MultipleRows.
• FieldDelimiter: how to delimit fields. Default is Tab.
• HeadersFootersBlanks: whether to export group headers, footers, and blank lines. Default is true.
• TextQualifier: how to qualify text fields. Default is DoubleQuote.

ScheduleData Sample Add-in

I created a sample application to demonstrate accessing the schedule data, and not just that. It also implements the following interesting additional features:

• Access and read back the schedule data from the exported text file into your application.
• Separately determine the schedule name, the column header names, and the schedule row data.
• Populate a DataTable instance with the retrieved schedule data.
• Create a new Windows form with a docked DataGridView in it programmatically, avoiding the need to define a hard-coded form in your add-in.
• Attach the form to the Revit main window, so that it is minimised and restored together with Revit.
• Populate the DataGridView from the DataTable and display the results.

I use the undocumented AdWindows assembly to determine the Revit parent window.

It returns the main window Revit handle in the static property ApplicationWindow of the ComponentManager class in the Autodesk.Windows namespace.

Here is the JtWindowHandle class that I use to convert the IntPtr returned by that property to the IWin32Window required by the Form.Show method:

  /// <summary>
  /// Wrapper class for converting 
  /// IntPtr to IWin32Window.
  /// </summary>
  public class JtWindowHandle : IWin32Window
  {
    IntPtr _hwnd;
 
    public JtWindowHandle( IntPtr h )
    {
      Debug.Assert( IntPtr.Zero != h,
        "expected non-null window handle" );
 
      _hwnd = h;
    }
 
    public IntPtr Handle
    {
      get
      {
        return _hwnd;
      }
    }
  }

Exporting the schedule data from Revit is really simple. Here is the implementation to export all schedule data in the entire model to separate text files with the filename extension TXT, defined by _ext, in a hard-coded folder, defined by _export_folder_name:

  FilteredElementCollector col
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ViewSchedule ) );
 
  ViewScheduleExportOptions opt 
    = new ViewScheduleExportOptions();
 
  foreach( ViewSchedule vs in col )
  {
    Directory.CreateDirectory( 
      _export_folder_name );
 
    vs.Export( _export_folder_name, 
      vs.Name + _ext, opt );
  }

The application then asks the user to select any one of the resulting text output files at a time to display its data in the data grid view. When the user cancels the file selection, the command is terminated:

  string filename;
 
  while( FileSelect( _export_folder_name, 
    out filename ) )
  {
    DisplayScheduleData( filename, 
      revit_window );
  }

Here is the DisplayScheduleData method that programmatically sets up a new Windows form, populates it with a docked DataGridView instance, and populates that with the schedule data retrieved from the output text files by the ScheduleDataParser class:

  void DisplayScheduleData( 
    string filename, 
    IWin32Window owner )
  {
    ScheduleDataParser parser 
      = new ScheduleDataParser( filename );
 
    System.Windows.Forms.Form form 
      = new System.Windows.Forms.Form();
    form.Size = new Size( 400, 400 );
    form.Text = _caption_prefix + parser.Name;
 
    DataGridView dg = new DataGridView();
    dg.AllowUserToAddRows = false;
    dg.AllowUserToDeleteRows = false;
    dg.AllowUserToOrderColumns = true;
    dg.Dock = System.Windows.Forms.DockStyle.Fill;
    dg.Location = new System.Drawing.Point( 0, 0 );
    dg.ReadOnly = true;
    dg.TabIndex = 0;
    dg.DataSource = parser.Table;
    dg.Parent = form;
 
    form.ShowDialog( owner );
  }

You could obviously make the form modeless instead of modal by calling Show instead of ShowDialog here. Since we are not accessing the Revit API from the form, there is no danger in leaving it open after the external command terminates. That would enable navigation and exploration of the schedule data in a modeless form in parallel with continued work in the Revit model.

Finally, here is the main point, the ScheduleDataParser class that I implemented to extract the schedule name, column headers, and schedule data from the text file and populate a DataTable instance with it:

class ScheduleDataParser
{
  /// <summary>
  /// Default schedule data file field delimiter.
  /// </summary>
  static char[] _tabs = new char[] { '\t' };
 
  /// <summary>
  /// Strip the quotes around text strings 
  /// in the schedule data file.
  /// </summary>
  static char[] _quotes = new char[] { '"' };
 
  string _name = null;
  DataTable _table = null;
 
  /// <summary>
  /// Schedule name
  /// </summary>
  public string Name 
  { 
    get { return _name; } 
  }
 
  /// <summary>
  /// Schedule columns and row data
  /// </summary>
  public DataTable Table 
  { 
    get { return _table; } 
  }
 
  public ScheduleDataParser( string filename )
  {
    StreamReader stream = File.OpenText( filename );
 
    string line;
    string[] a;
 
    while( null != ( line = stream.ReadLine() ) )
    {
      a = line
        .Split( _tabs )
        .Select<string, string>( s => s.Trim( _quotes ) )
        .ToArray();
 
      // First line of text file contains 
      // schedule name
 
      if( null == _name )
      {
        _name = a[0];
        continue;
      }
 
      // Second line of text file contains 
      // schedule column names
 
      if( null == _table )
      {
        _table = new DataTable();
 
        foreach( string column_name in a )
        {
          DataColumn column = new DataColumn();
          column.DataType = typeof( string );
          column.ColumnName = column_name;
          _table.Columns.Add( column );
        }
 
        _table.BeginLoadData();
 
        continue;
      }
 
      // Remaining lines define schedula data
 
      DataRow dr = _table.LoadDataRow( a, true );
    }
    _table.EndLoadData();
  }
}

Here is a sample schedule in Revit to test this on:

This is the resulting data grid view representation:

Here is ScheduleData.zip containing the complete source code, Visual Studio solution and add-in manifest for this add-in.

On a closely related note, here is another question that just came in:

Question: Can calculated values in schedules be transferred to a shared parameter with some API code?

Answer: Sure. Just access the schedule data as demonstrated above, and then write the relevant value to the shared parameter.

Read-only and Automatic Transaction Modes

We have been discussing transactions and their disposal quite a bit recently, with lots of interesting input from Guy Robinson and Arnošt Löbel.

They just submitted comments on EditFamily requiring a non-modifiable document which highlight another issue in this area worthwhile promoting to a post of its own to ensure that you take notice:

Guy says: ... maybe it's time to recommend using the Manual transaction mode only and the removal of Automatic mode. This would pave the way for removing the transaction and regeneration attributes all together.

Jeremy says: I personally never use automatic transaction mode, but I do use both the manual and read-only ones.

It would actually be interesting to know the exact difference between an external command using read-only mode and one using manual without opening any transactions.

Arnošt says: I believe I said it publicly before, but probably not on this blog yet:

First of all, Automatic Transaction Mode is considered obsolete, and we (Autodesk.Revit) do not recommend using it for new external applications. It only exists to ensure compatibility with older applications. The Automatic mode has many limitations (for what an external command can or cannot do), while it has virtually no benefits whatsoever. It is likely it will go away in some future release of Revit.

Read-Only transaction mode does two things (well, it's one thing, really, but I'll split it):

• For one, the command using it cannot have any transactions and may not call any methods that modify a document, directly or indirectly, or even temporarily.
• Secondly, while this external command is being executed, nobody else is allowed to modify the document or have a transaction either; that includes Revit itself, but also applies to other applications that might be invoked through events (for example).

All this basically guarantees that during the entire execution of the external command the current models all remain unmodified.

Guy sums up enthusiastically: Yes, I've been a manual transaction person for a long time.

For various reasons, this enjoyable and thought provoking discussion has accelerated a process I have been slowly going through since the R13 alpha's. The richness of the R13 API effected a rethink, and issues such as transactions/exceptions, which I'll admit I hadn't changed my approach to for a very long time, are triggering more fundamental changes in attitude to the API.

I'd have to say compared to the R8 API I first played with a very long time ago, the speed, stability and functionality possible now is quite stunning. And thinking why these scoping and other changes could be happening is making me rather excited.

With Win8/WinRT/iOS/mobile etc., though, apart from keeping it all logically in my brain it all makes for exciting times as a programmer, even if there aren't enough hours in the day ;-)

Jeremy replies: Wow, yes, talking about cloud and mobile computing and enough hours in the day, have you looked at Kean's latest posts on creating a 3D Android viewer, calling a web-service from Unity, etc.?

Many thanks to Guy and Arnošt for this and all the other recent interesting discussions and insights!

DevDays Online on What's New in Revit 2013

A recording of the "What's New in the Revit 2013 API" presentation from the DevDays conferences that we presented on the world-wide tour during the winter months is now live, both by selecting "DevDaysOnline-Revit2013API" in the public ADN webcast recording archive (download recording) and on the members-only ADN web site.

The 88 MB download contains the following:

• Recording – MP4 and supporting files (73,682,898 bytes)
• Presentation – DevDays Online - Revit 2013_Whats New.pptx (4,915,103 bytes)
• Sample code
  • ReadMe.txt
  • RoutingPreferenceAPI
  • ScheduleAPI
  • StairsAPI
  • UIAPI

The samples have also made it into the updated Revit 2013 SDK by now.

The presentation includes a product overview and a summary of the new API features, obviously going into much more detail than my recent brief overview of Revit 2013 and its API.

To give you an idea of the new product features, here is the list of main Revit 2013 product related projects:

• Construction, Fabrication and Engineering
  • Construction Modeling
  • Fabrication Platform
  • Precast Elements
  • Reinforcement Detailing
  • Point Clouds
  • Piping & System Routing
  • Customer Requests
• Platform Scalability
  • Revit Server
  • Performance
• Countrification
  • Stairs & Railings
  • MEP Centerlines
  • IFC API
• Suites & Interoperability
  • First Experience
  • Revit One Box
  • Consistent Visualization
  • Translation Fidelity
  • Add-In Integration
  • View API
  • Visualization API
  • Suites Visualization Workflows
  • Inventor Interoperability API
• Analysis & Simulation
  • Physical Properties
  • Structural Analysis in BIM
  • Structural Code Checking
  • Analysis Visualization
  • Analytical Volumes
  • MEP Calculations

For more details on the new product features, you can check out the

• New feature videos and
• What's New section in the developer guide.

On the API front, I mentioned the main topics already in my Revit 2013 API overview, without, as said, being able to go into as much detail as this presentation does.

Many thanks to Saikat Bhattacharya for creating this recording!

Edit Family Requires No Transaction

I recently received a note from Matt Mason pointing out that the behaviour of the EditFamily method changed in Revit 2013, and a suggestion to highlight this fact. The suggestion is very valid, since his note was quickly followed up by a matching question by Woong Ki Sung on reloading a family, who ran into the very same issue:

Question: I am testing some code to edit family types in Revit 2013, and I have a transaction problem even though I set up manual transactions properly.

The code is very simple, so could you please check? In advance, thank for your help.

Here is the answer by Matt:

Answer: A quick note after I saw your recent post on upgrading add-ins.

I had an interesting case the other day: there is a new API requirement in 2013 that all transactions must be closed before calling EditFamily – it throws an exception to that effect.

I hadn't really focused on this before, and the add-in in question was actually still set up for Automatic mode – I had to convert my add-in to manual transaction mode so that I could control the transactions and close them all prior to calling EditFamily.

The remarks on the EditFamily method in the Revit 2013 API help file RevitAPI.chm now clearly state:

Gets the document of a loaded family to edit. This creates an independent copy of the family for editing. To apply the changes back to the family stored in the document, use the LoadFamily overload accepting IFamilyLoadOptions.

This method may not be called if the document is currently modifiable (has an open transaction) or is in a read-only state. The method may not be called during dynamic updates. To test the document's current status, check the values of IsModifiable and IsReadOnly properties.

Many thanks to Matt for pointing this out!

Developer Center and SDK Update

I enjoyed the first really hot weekend this spring. It was warming up seriously last week in Munich, and now it feels as if we were suddenly catapulted from a hesitant spring straight into summertime. I also took some time to explore the developer centre and Revit 2013 SDK update, though.

The Revit Developer Center has been updated to a new layout.

The API and the available training material have grown so fast and voluminous that the old layout was getting hard to navigate. I hope the updated site makes it easier still for you to quickly find exactly what you need. Take a look and let us know what you think.

At the same time, the Revit SDK has been updated. If you are using the SDK, I recommend that you immediately switch to the updated version.

Revit 2013 Developer Guide

Some developers asked about the Revit 2013 developer guide, pointing out that it is not included in the SDK in PDF format as it was in previous releases.

The fact is that the one and only official version of the Revit API Developer Guide is the one provided online at wikihelp.autodesk.com/Revit/enu/2013 > API Developer's Guide.

The developer guide has been available online for a year and is now 100% on wikihelp. The PDF provided in previous releases was never as up-to-date as the wikihelp location.

Work on the 2013 version is still underway, and it is already in a completely usable state.

More New Revit 2013 SDK Samples

I recently presented an overview of the enhancements, new functionality and six new SDK samples provided by the Revit 2013 API:

• ModelessForm_ExternalEvent and ModelessForm_IdlingEvent (ModelessDialog)
• ProgressNotifier (Events)
• RoutingPreferenceTools
• UIAPI
• WorkThread (MultiThreading)

The updated version includes three more ones in addition to those:

• DisableCommand
• ScheduleCreation
• StairsAutomation

These three all have to do with the enhanced add-in integration supported by Revit 2013, and just like several of the previous samples, they were demonstrated at the DevDays 2011 conferences by the Revit UI API demo sample application, which is available for ADN members together with all other DevDays presentations on the ADN Extranet at adn.autodesk.com under "Events".

The only noteworthy other changes in the updated version are the inclusion of the three new samples plus the UIAPI one to the SDKSamples2013.sln Visual Studio solution file, and the addition of these four plus CompoundStructure to the SamplesReadMe.htm documentation file.

Well, OK, the What's New section of the Revit API help file RevitAPI.chm has been revamped and looks nicer, as well.

Compiling and Installing the Revit SDK

To compile the new version of the SDK, I had to go through the same steps as always:

1. Compile and install RevitLookup
2. Compile the SDK samples
3. Install RvtSamples

1. Compile and install RevitLookup. Nothing special here; just open the project file, compile, edit the add-in manifest, and copy it to the add-ins folder.

2. Compile all the SDK samples using the SDKSamples2013.sln Visual Studio solution. This requires updating the Revit API assembly DLL paths in the project files to whatever version of Revit I have installed. In my case, I still only have the Revit Quasar RP version installed, whereas the project files refer to Revit Architechture 2013, Revit MEP 2013 and Revit Structure 2013.

One way to do this is to use the RevitAPIDllsPathUpdater.exe provided in the SDK Samples folder.

I prefer not to modify the HintPath tags in the project files at all, but rather to simply create dummy directory structures for the three products under the Program Files > Autodesk root folder and copy the required DLLs into a Program subfolder in each of them, ending up with the following seven copied assemblies:

• C:\Program Files\Autodesk\
  • Revit Architecture 2013\Program\
    • RevitAddInUtility.dll
    • RevitAPI.dll
    • RevitAPIUI.dll
  • Revit MEP 2013\Program\
    • RevitAPI.dll
    • RevitAPIUI.dll
  • Revit Structure 2013\Program\
    • RevitAPI.dll
    • RevitAPIUI.dll

The copy of RevitAddInUtility.dll in the architectural dummy folder is only required to compile the ExternalCommand RevitAddInUtilitySample SDK sample. By the way, the location of this reference is not updated by RevitAPIDllsPathUpdater.exe, like the other two main Revit API assembly DLLs. It would help if the source code for this utility were available.

I also had to change the ProgressNotifier sample Revit API assembly reference paths, which were hardwired to 64 bits.

Once that was done, the SDKSamples2013.sln solution compiled all SDK samples with no problems.

3. Set up RvtSamples to load all SDK samples into Revit.

To achieve this, I had to set up and install RvtSamples and make a few fixes to the text file it reads to specify the locations of all the samples to load; here is my slightly updated version of RvtSamples.txt.

All in all this is a very clean update with only minor changes required to set it up on my system.

Now let's take a look at the three newly introduced SDK samples.

DisableCommand

This sample is an external application, not a command, so you cannot test it by simply invoking it via RvtSamples. You have to copy its add-in manifest to the add-ins folder.

Once installed, it disables a command by replacing its implementation with a simple popup message. Specifically, it overrides the Design Options command, thus prevent users from accessing it. It performs the following steps:

• A RevitCommandId is found to match the journal name of the command.
• An AddInCommandBinding is created for this command id.
• An alternate implementation is provided for the command binding.

To run it, once installed, simply start up Revit, open or create a project, and choose the Design Options button on the Manage tab. A popup explains that the command is disabled:

ScheduleCreation

This sample demonstrates how to create a wall category view schedule and display its data on a sheet. It performs the following steps:

• Create an empty wall schedule.
• Add some schedule fields by schedulable field.
• Create new schedule filter.
• Create schedule sorting/grouping field.
• Display a sheet containing the wall schedule.

Run it as follows:

1. Open Revit and create a new project based on the default Revit template.
2. Manually create a couple of walls with different types.
3. Run this command, for instance via RvtSamples > Views > ScheduleAPI.
4. A view schedule of wall category and a sheet to show its data are created.

Here is a trivial sample model to test it in:

This is the resulting schedule:

StairsAutomation

This is a slightly more complex sample that creates a series of stairs, stairs runs and stairs landings configurations based upon predefined hard-wired rules and parameters. It provides an example of how to create and populate stairs elements, e.g.

• Use of StairsEditMode
• Creation of standard stairs runs
• Creation of sketched stairs runs
• Creation of sketched landings

It also implements an extensible structure demonstrating how runs and landings creation can be combined into different stairs configurations.

To test this, start up Revit and open the 'Stairs automation.rvt' sample model. Execute the command, e.g. using RvtSamples > Elements > Stairs automation. Each time the command is run, a different predefined stair configuration is created:

1. Single straight stair run

2. Stairs/landing combination up to level 2

3. Multi-span stairs/landing combination up to level 3

4. Single curved stairs run

5. Curve stairs run > 360 degrees

As said, a clean and interesting update, and I highly recommend you grab and install it.