The Building Coder

Select Model Elements 2

We already had several stabs at the topic of selecting all model elements, i.e. all elements in a Revit BIM which contribute to the building geometry. Their main characteristic is that they have a non-null geometry which is visible on the graphics screen and really contributes to the physical building model. Unfortunately, some elements which are not part of the building itself also have valid geometry and need to be eliminated.

The latest version of the code that we presented still made use of a full iteration over all document elements, i.e. something like this:

  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  ElementIterator it = doc.Elements;
 
  while( it.MoveNext() )
  {
    Element e = it.Current as Element;
    // . . .
  }

As we all know by now, this kind of full iteration over all document elements is unnecessarily time consuming and seldom useful, because an application is almost always only interested in a small subset of them. We will convert the model element selection to use element filtering, similarly to the conversion to use filters we described for the Revit SDK FrameBuilder sample.

We can add both a type filter to eliminate a list of classes that we are not interested in, and also a built-in category filter to eliminate unwanted categories. Here is the list of unwanted types, i.e. classes of elements which are not model elements:

static Type[] _types_to_skip = new Type[] {
  typeof( BasePoint ),
  typeof( DetailLine ),
  typeof( Dimension ),
  typeof( Family ),
  typeof( FamilyBase ),
  typeof( FillPattern ),
  typeof( gbXMLParamElem ),
  typeof( GraphicsStyle ),
  typeof( Level ),
  typeof( LinePattern ),
  typeof( MaterialOther ),
  typeof( ModelLine ),
  typeof( Phase ),
  typeof( PrintSetting ),
  typeof( ProjectInfo ),
  typeof( ProjectUnit ),
  typeof( ReferencePlane ),
  typeof( Room ),
  typeof( RoomTag ),
  typeof( Sketch ),
  typeof( SketchPlane ),
  typeof( Symbol ),
  typeof( TextNote ),
  typeof( ViewDrafting ),
  typeof( ViewPlan ),
  typeof( ViewSheet ),
  typeof( WallType ),
};

If you run into some additional unwanted element in your model that is not listed here, you can easily add it. You might want to let us know as well by submitting a comment on it.

We define the following helper method to more succinctly create a type filter which eliminates all of these classes. Given an existing type filter 'f', it adds another type 't' to it and returns the new expanded filter:

static Filter OrType(
  Filter f,
  Type t,
  Autodesk.Revit.Creation.Filter cf )
{
  Filter f2 = cf.NewTypeFilter( t );
  return cf.NewLogicOrFilter( f, f2 );
}

We can make use of it to implement the first step of our external command Execute method like this:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
 
Autodesk.Revit.Creation.Filter cf
  = app.Create.Filter;
 
List<Element> els = new List<Element>();
Filter f = cf.NewTypeFilter( typeof( Symbol ) );
foreach( Type t in _types_to_skip )
{
  f = OrType( f, t, cf );
}
f = cf.NewLogicNotFilter( f );
int n = doc.get_Elements( f, els );

In addition to the unwanted types, we know some built-in categories whose elements also do not contribute to the building geometry and should be eliminated, for instance:

static int[] _bics_to_skip = new int[] {
  ( int ) BuiltInCategory.OST_PreviewLegendComponents,
  ( int ) BuiltInCategory.OST_IOSSketchGrid,
  ( int ) BuiltInCategory.OST_Cameras,
};

We have converted them to integer values to make use of the language independent category comparison. The following helper method encapsulates the code to determine whether a given built-in category integer value is included in this list and the associated element thus needs to be skipped. It makes use of the generic Array.Exists method:

static bool SkipThisBic( int bic )
{
  return Array.Exists<int>(
    _bics_to_skip,
    delegate( int i )
    {
      return i == bic;
    } );
}

With these preparations in place, we can iterate over and list the model elements like this in the rest of the implementation of the external command Execute method:

string s = string.Empty;
n = 0;
 
Geo.Options opt = app.Create.NewGeometryOptions();
 
foreach( Element e in els )
{
  if( (null != e.Category)
    && !SkipThisBic( e.Category.Id.Value )
    && (null != e.get_Geometry( opt )) )
  {
    ++n;
    s += string.Format( 
      "\r\n  Category={0}; Name={1}; Id={2}",
      e.Category.Name, e.Name, e.Id.Value );
  }
}
 
s = string.Format(
  "Project contains {0} model element{1}{2}",
  n,
  ( 1 == n ? "" : "s" ),
  ( 0 == n ? "." : ":" ) )
+ s;
 
LabUtils.InfoMsg( s );
 
return CmdResult.Failed;

Here is today's snapshot of the updated version of the Revit API introduction labs including the version of Lab 2-2 to select all model elements as described above.

Revit Family Creation API Labs

The handouts and presentation for my Autodesk University family API session are finally done, as well they should be, since they are due to be submitted by today. The last part I worked on was to add more documentation on the family API labs to the handout document. I think this overview will be of interest here as well. The family API labs were originally created and documented by Mikako Harada, the ADN AEC workgroup lead, so all of the material presented here is due to her. Talking about that prompts me to mention the webcasts where this material was first used:

ADN webcast registration statistics

Most of the material that I am presenting at AU was originally prepared for webcasts on the Revit Family API and MEP API and then posted to this blog as well. Mikako just sent around some statistics on the numbers of registrations for the various webcasts held by the Autodesk Developer Network this year. The overview of all webcasts and other training classes is available online from the Autodesk Developer Network API training schedule. All in all, we presented on 25 different topics and had a total of 1576 attendees registered. The absolute leader in the number of registrations was the Revit API webcast with 250, followed by the Inventor API with 100. The Revit family and MEP API webcasts were also pretty popular with 75 and 64 respectively, so the three Revit webcasts together attracted 389 out of 1576 registrations or about 25%. This just goes to show that the Revit API is an important and popular topic.

Family API Labs: Creating an Example Family

Returning to the Revit Family API Labs, they are a collection of exercises which introduce you step by step to the creation of a column family. The objective is to learn the basics of the family API. The labs start at zero and proceed through the absolute beginning steps up to slightly more advanced aspects. Here are the four steps of increasing complexity covered:

1. Define a rectangular profile column family.
2. Define an L-shaped profile column family.
3. Add formulae and materials.
4. Add visibility control.

The full Visual Studio solution and projects, source code, detailed documentation and instructions for each step are included separately for both C# and VB. Here is an overview of the main files and directories:

• rfa_labs.sln – common C# and VB Visual Studio solution file
• cs – C# source code directory
  • LabsCs.csproj
  • 1_ColumnRectangle.cs
  • 2_ColumnLshape.cs
  • 3_ColumnFormulaMaterial.cs
  • 4_ColumnVisibility.cs
  • Util.cs
• csdoc – C# documentation and detailed step-by-step instructions directory
  • Family Lab1 - Create Rectangular Column_CS.rtf
  • Family Lab2 - Create L-Shape Column_CS.rtf
  • Family Lab3 - Add Formula and Material_CS.rtf
  • Family Lab4 - Add Visibility Control_CS.rtf
• vb – VB source code directory
  • LabsVb.vbproj
  • 1_ColumnRectangle.vb
  • 2_ColumnLshape.vb
  • 3_ColumnFormulaMaterial.vb
  • 4_ColumnVisibility.vb
• vbdoc – VB documentation and detailed step-by-step instructions directory
  • Family Lab1 - Create Rectangular Column.rtf
  • Family Lab2 - Create L-Shape Column.rtf
  • Family Lab3 - Add Formula and Material.rtf
  • Family Lab4 - Add Visibility Control.rtf

The source code and instruction documents are part of the Family API webcast materials. For your convenience, I am including them here as well.

The following summary provides a high-level overview of the implementation. Detailed information and step-by-step instructions are provided in the source code comments and the dedicated csdoc and vbdoc documents.

Lab 1 – Create Rectangular Column

The first lab demonstrates how to implement the following four essential basic steps for creating a new family:

1. Check the family context and category.
2. Create a simple solid using extrusion.
3. Set alignments.
4. Add types.

It makes use of the following classes and methods:

doc.IsFamilyDocument
doc.OwnerFamily.FamilyCategory.Name
doc.FamilyCreate.NewExtrusion()
doc.FamilyCreate.NewAlignment()
familyMgr = doc.FamilyManager
familyMgr.NewType()
familyMgr.Parameter(); familyMgr.Set()

Here is an overview of the four steps listed above in slightly greater detail:

1. In the first lab, we create a simple rectangular column family defining three column types with different dimensions. Before proceeding with the definition of the geometry and types, we need to ensure that we are working in a family template file and the correct family category. The document provides a property IsFamilyDocument to check the former, and the owner family category gives us the category of the template file.
2. Creating the geometry is easily achieved by defining a rectangular profile in the XY plane and extruding it using the NewExtrusion method. When creating the geometry, we need to account for the Revit database units and convert all our length measurements to feet.
3. One method to drive the geometry parametrically is to specify alignments between certain parts of the geometry and reference planes. In this very simple case, the template file already provides six reference planes for the upper and lower levels and the right, left, front and back faces, and we have six corresponding faces on the column. We need to specify alignments between these reference planes and the corresponding faces of our solid extrusion. This is done by identifying the matching pairs of solid face and reference plane and calling NewAlignment for each. In this simple case, the solid faces can be identified by their normal vectors and the reference planes by their names. In a more complex case, such as the next example in lab 2, we may have to create the reference planes ourselves, and use more complex algorithms to identify the reference planes and the solid geometry faces to associate with each other.
4. Finally, we create a few sample types for the family. In this simple case again, the template file already defines the parameters that we require for this, namely Width and Depth. Lab 2 will demonstrate how to define our own new parameters. Since the parameters are given, all we need to do is access the FamilyManager object and use its AddType and get_Parameter methods to specify the types to create and their dimensions.

Further in-depth details on the process and source code snippets to achieve each of these four steps is given in the separate documents 'Family Lab1 - Create Rectangular Column.rtf' in the csdoc and vbdoc subdirectories for C# and VB, respectively.

Lab 2 – Create L-Shaped Column

The second lab builds on the first to define a column with a slightly more complex L-shaped cross section profile. Due to this, the predefined reference planes and parameters provided by the template file are not sufficient to drive all aspects of the geometry, so we have to create our own additional ones. To be precise, we need reference planes, parameters and dimensions to determine and measure the thickness of the two 'legs' of the L shape.

Also, in the L-shaped column solid, the normal vector alone is not enough to identify all of the individual solid faces, so that algorithm needs to be refined as well. In our case, we use the reference plane associated with each solid face to identify it.

Finally, the lab also demonstrates adding new dimensioning to the family definition. The following steps are added to the existing ones:

• Add reference planes.
• Add parameters.
• Add dimensions.

The classes and methods used include:

doc.FamilyCreate.NewReferencePlane()
familyMgr.AddParameter()
doc.FamilyCreate.NewDimension()

Separate C# and VB versions of the detailed instructions, explanations, and source code snippets for this lab are provided by the document 'Family Lab2 - Create L-Shape Column_CS.rtf' in the csdoc and vbdoc subdirectories of the sample material.

Lab 3 – Add Formulae and Materials

In the third step, we further enhance the column family defined in the previous step by defining formulae for the L shape leg width parameters and by assigning a material to one of the family types.

• Add formulae.
• Add materials.

The classes and methods used include:

familyMgr.SetFormula()
pSolid.Parameter("Material")
familyMgr.AddParameter()
familyMgr.AssociateElementParameterToFamilyParameter()

The two parameters are defined as formulae so that the L shape leg width equals a quarter of the column width, and similarly for the depth. The key here is the family manager SetFormula method.

For the material, an instance parameter for the material group is added to the family and associated with the material parameter of the solid. Here, the key is the AssociateElementParameterToFamilyParameter method.

Again, separate C# and VB versions of the detailed instructions, explanations, and source code snippets for this lab are provided by the document 'Family Lab3 - Add Formula and Material_CS.rtf' in the csdoc and vbdoc subdirectories of the sample material.

Lab 4 – Add Visibility Control

Performance is a critical aspect of building family content, and significant performance improvements can be achieved by making use of the visibility settings accessible for each element in a family through the FamilyElementVisibility class, which can define which levels of detail and which types of views it appears in. That is the focus of this final lab, which implements the following:

• Implement a single line representation for the column in coarse view:
  • Single symbolic line representation in plan view.
  • Single model line representation in model view.
• Set the visibility control so that the single line representation is used in coarse view.

The classes and methods used include:

doc.FamilyCreate.NewSymbolicCurve()
doc.FamilyCreate.NewModelCurve()
FamilyElementVisibility(FamilyElementVisibilityType.ViewSpecific/Model)
FamilyElementVisibility.IsShownInFine, etc.
pLine.SetVisibility(pFamilyElementVisibility)

The detailed documentation and C# and VB code snippets for this lab are provided by the document 'Family Lab4 - Add Visibility Control_CS.rtf' in the csdoc and vbdoc subdirectories of the sample material.

Three Coding and Performance Hints

We received three interesting and important coding and performance hints from Piotr and Guy Robinson on the post on Linq yesterday. I find them too important to leave them dozing away in the comment section, so here is their promotion to post status:

1. Use auto-implemented properties to simplify the helper class code.
2. Use ParametersMap instead of looping over all element parameters.
3. The .NET Framework 3.5 SP1 is significantly improved over .NET 3.5.

As Piotr pointed out, auto-implemented properties are a nice new feature that has been available since .NET 3.0. It saves some typing and significantly simplifies and shortens the helper class definition.

Guy underlined that Joel's speed increases probably are a result of using proxy objects rather than Linq. Proxies are useful for data binding as well, though, so they get used more often than not, and Linq is pretty cool. Also, using .NET3.5SP1 is much better than .NET3.5. It includes a number of important fixes, and WPF is faster with SP1.

Guy also points out that looping over all the element parameters of each element is very costly, so you will get a nice additional speed improvement and a simpler class again for large datasets by using the ParametersMap in the constructor, rather than looping through all parameters.

Jeremy adds that you should please be aware that using the parameter name strings as keys in the parameter lookup has the disadvantage of making the code language dependent. If possible, that should be avoided, and built-in parameter enumeration values or GUIDs should be used instead. I should think that is faster still, though maybe only marginally.

This is what the helper class definition looks like after applying the first two recommendations:

class InstanceData
{
#region Properties
public Element Instance { get; set; }
public String Param1 { get; set; }
public bool Param2 { get; set; }
public int Param3 { get; set; }
#endregion
 
#region Constructors
public InstanceData( Element instance )
{
  Instance = instance;
 
  ParameterMap m = Instance.ParametersMap;
 
  Parameter p = m.get_Item( "Param1" );
  Param1 = ( p == null ) ? string.Empty : p.AsString();
 
  p = m.get_Item( "Param2" );
  Param2 = ( p == null ) ? false : ( 0 != p.AsInteger() );
 
  p = m.get_Item( "Param3" );
  Param3 = ( p == null ) ? 0 : p.AsInteger();
}
#endregion
}

Many thanks again to Joel for the original article and to Piotr and Guy for the valuable hints!

I still wonder whether using ParametersMap is faster than simply using Parameters. Another interesting thing to look at some day would be a benchmark comparing various different parameter access methods. One of these days, when we have lots of time ...

Language Integrated Query Linq

The Language Integrated Query or Linq is a .NET Framework component that adds powerful native data querying capabilities to .NET languages.

Here is a contribution by Joel Karr of Environmental Systems Design, Inc on this exciting topic, demonstrating how it can be used to achieve huge performance improvements when analysing large Revit models.

Using LINQ to Query

Here at Environmental Systems Design, www.esdesign.com, we have seen that a simple task in Revit, such as changing a single parameter of an object, can take an immense amount of time when multiplied over thousands of elements in a model. Through the use of LINQ, we have found that we have a wide range of powerful query tools that can help us avoid the costly time associated with constant calls to the Revit API. We can store the information we need once, and then efficiently query that data in a similar way to the familiar SQL database queries.

LINQ was introduced with the .NET Framework 3.5. The main benefit is an advanced native data query capability. For example, if we wanted to find all diffusers in a model that had a CFM of over 500, we could use a LINQ query to find them:

  var results 
    = from d in allDiffusers
      let x = 500
      where d.CFM < x
      select d;

Although LINQ takes a little more time to set up initially, repeated queries will perform much faster. We had an instance where we wanted to place nearly 15,000 connectors in our model to correspond with an architectural model.

LINQ queries have a running time of O(n), but when used with Revit we find that we can greatly reduce our search time if we store information in an object that we will reuse. Our initial method kept a list of elements and then checked each element.Location for a match. This caused us to use the Revit API thousands of times unnecessarily. By storing the location in an object and then using LINQ to find a match, our process time went from over 14 hours down to under 10 minutes.

We created an object that stored the information about each lighting fixture in the architect's model and also the information we needed about our connectors. Through the use of a LINQ query, we were able to search to see if a connector existed at the same location as the architect's lighting fixture.

It became as simple as the following code to find out if a connector existed in the same location as the lighting fixture we were checking:

  var found 
    = from con in Connectors
      where con.ConLocation.Equals( location )
      select con;

LINQ can work with a ton of different type of data sources. Some of the most popular are SQL, XML, ADO.NET datasets, .NET objects and several other third party sources which even include an ongoing project for the creation of LINQ to Google. In order to keep our code self contained and as simple as possible, we create a custom object to use with our LINQ queries.

To start with, we need to create a new class to store the information that we would like to query:

class InstanceData
{
  #region Field Data
  private Element _instance;
  private String _param1;
  private bool _param2;
  private int _param3;
  #endregion
 
  #region Properties
  public Element Instance
  {
      get { return _instance; }
      set { _instance = value; }
  }
  public String Param1
  {
      get { return _param1; }
      set { _param1 = value; }
  }
  public bool Param2
  {
      get { return _param2; }
      set { _param2 = value; }
  }
  public int Param3
  {
      get { return _param3; }
      set { _param3 = value; }
  }
  #endregion
 
  #region Constructors
  public InstanceData( Element instance )
  {
    Instance = instance;
 
    foreach( Parameter param in Instance.Parameters )
    {
      // Param1 returns string value
      if( param.Definition.Name == "Param1" )
      {
        Param1 = param.AsString();
      }
 
      // Param2 is a checkbox returning 0 or 1
      if( param.Definition.Name == "Param2" )
      {
        Param2 = (0 != param.AsInteger());
      }
 
      // Param3 returns an integer value
      if( param.Definition.Name == "Param3" )
      {
        Param3 = param.AsInteger();
      }
    }
  }
  #endregion
}

Now that we have our custom class created, we just need to populate it with the data we would like to query. This can be done many ways. For this example we will simply retrieve all the family instances in the model:

CreationFilter cf = app.Create.Filter;
Filter f1 = cf.NewTypeFilter( typeof( FamilyInstance ) );
 
List<Element> a = new List<Element>();
doc.get_Elements( f1, a );
 
List<InstanceData> instanceDataList 
  = new List<InstanceData>();
 
foreach( Element e in a )
{
  instanceDataList.Add( 
    new InstanceData( e ) );
}
 
string s = "value1";
bool b = true;
int i = 42;
 
var found = from instance in instanceDataList where 
  (instance.Param1.Equals( s )
  && b == instance.Param2
  && i < instance.Param3)
select instance;
 
foreach( InstanceData instance in found )
{  
  // Do whatever you would like
}

So that was it from Joel, and back to Jeremy again. Thank you ever so much, Joel, for this fantastic introduction and example!

While preparing this article, I was a bit stumped to compile the sample code as part of The Building Coder samples until I noticed that I have to switch to the .NET Framework 3.5 before I can use Linq in C#. Watch out for this if you are trying to add Linq functionality to existing older projects.

Two things to note here, which make this information ever more globally usable:

• This is a very powerful optimisation technology in any environment, whether inside of Revit or elsewhere.
• Possibly the same kind of performance enhancement could be achieved by using some other caching mechanism independent of Linq. The main factor here is possibly the local storage of the data to be processed, avoiding repeated expensive calls to query it from Revit.

One extremely powerful advantage of Linq is its extremely readable query syntax.

Category Comparison and Model Elements Revisited

This is a follow-up to two previous posts, on category comparison and the selection of model elements.

Regarding the category comparison, we discussed the fact that categories cannot be compared directly, and one should use their element id instead. We also underlined that every category comparison should be made language independent by using the built-in category enumeration and not comparing the localised category names. The analysis of the model element selection examined how to eliminate the preview legend components from the selected elements, since they suddenly acquired geometry in Revit 2010 and also fit the other criteria applied in the selection process.

As Miroslav Schonauer pointed out, the model element selection that I suggested in that post will not work, because various model elements exist that do not have a valid level assigned to them. He suggests that the previous selection algorithm with an additional check added for the preview legend components probably remains the simplest and most reliable method.

One deplorable aspect of the code presented there with the preview legend component check added is its language dependence. It compares the element category name with the preview legend component one, which is "Legend Components". I left that in there because I thought I would use the alternative approach anyway, checking for a valid level.

So now the issue is how to compare a given element's category against a built-in one without using the category name. In previous similar situations, I achieved this by asking the document for the built-in category object and using its element id. The Revit developers guide includes some sample code which demonstrates an extremely effective alternative method. It avoids the string comparison and achieves language independence, and it also does not require the effort of querying the document settings for the element id of a built-it category.

For built-in categories, the value of the element id is exactly the same as the integer resulting from casting the built-in category enumeration value. The section 5.2.1 Category discusses details of the element category classification and explains:

An element's category is determined by the Category ID.

• Category IDs are represented by the ElementId class.
• Imported Category IDs correspond to elements in the document.
• Most categories are built-in and their IDs are constants stored in ElementIds.
• Each built-in category ID has a corresponding value in the BuiltInCategory Enumeration. They can be converted to corresponding BuiltInCategory enumerated types.
• If the category is not built-in, the ID is converted to a null value.

The Code Region 14-1: 'Distinguishing permanent dimensions from constraints' in section 14.1 'Dimensions and Constraints' shows that we can actually use the built-in enum value to compare with an element category id directly, as in the following excerpted lines:

  if ( (int) BuiltInCategory.OST_Dimensions
    == dimension.Category.Id.Value )
  {
    message += "\nDimension is a permanent dimension.";
  }

Making use of this for the model element selection, we can implement the following filter which is both language independent and efficient:

BuiltInCategory _bicPreviewLegendComponent 
  = BuiltInCategory.OST_PreviewLegendComponents;
 
public CmdResult Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  ElementIterator it = doc.Elements;
  string s = string.Empty;
  int count = 0;
 
  Geo.Options opt = app.Create.NewGeometryOptions();
 
  int iBic = (int) _bicPreviewLegendComponent;
 
  while( it.MoveNext() )
  {
    Element e = it.Current as Element;
 
    if ( !(e is Symbol)
      && !(e is FamilyBase)
      && (null != e.Category)
      && ( iBic != e.Category.Id.Value )
      && (null != e.get_Geometry( opt )) )
    {
      ++count;
      s += string.Format( 
        "\r\n  Category={0}; Name={1}; Id={2}",
        e.Category.Name, e.Name, 
        e.Id.Value.ToString() );
    }
  }
 
  s = "There are " + count.ToString() 
    + " model elements:" + s;
 
  LabUtils.InfoMsg( s );
 
  return CmdResult.Failed;
}

Here is a snapshot of an updated version of the Revit API introduction labs including the updated version of Lab 2-2 to select all model elements using this criterion and other on-going improvements we have made. In particular, it includes two completely new modules, Labs6 dealing with external application and event issues, and Labs7 demonstrating the form creation API. We are still continuing the process of updating and enhancing them for the Revit 2010 API and its new features. All of the labs are provided in two versions, one each for C# and VB. This version also includes a set of HTML instructions for self-learning and AdnSamples.txt, an include file for RvtSamples that I use to load all my external commands, updated to the 2010 RvtSamples format.

Revit Inside

By the way, if you are interested in seeing who else is using Revit, there is a Revit Inside website which tells you just that. The people running the list are always interested in new entries as well, so don't hesitate to check it out and sign up if it applies to you.

Imports in Families

I will have left on vacation once again by the time this is posted. In case you wonder why I am on vacation so much, the trip to Italy in March and the wonderful experiences I had there were actually to use up last year's contingent. Now I am getting started on this years', going off on a climbing and driving trip to southern France with my two sons Christopher and Cornelius, especially to the Provence and Avignon to visit my mother, sister and nephew. So I will be posting a bit less or not at all for the coming two weeks.

Before leaving, though, here is an interesting and practically oriented question by my colleague Martin Schmid of Autodesk. I wrote a new command for The Building Coder samples to answer it, which may even be useful for some in everyday life. Martin is an experienced AutoCAD MEP and Revit MEP expert and application engineer and helped me a lot with the preparation of the Revit MEP API class at Autodesk University.

Question: How hard do you think it would be to put together a quick bit of code that would:

1. Iterate over all family definitions in a project.
2. For each family definition, identify if there are any ‘import symbols’, i.e., imported DWG, SAT, DXF and other non-native Revit geometry?

The reason I ask is that performance is degraded if very complex geometry is imported. Some complaints about performance were caused by such complex imported geometry.

I have an example demonstrating slow graphics generation in a mechanical view with an ‘offending’ family. It takes more than 30 seconds to zoom in on the area with the ‘bad’ family. In the family editor, one can see that there is an imported DXF symbol at that location. If you return to the project and delete the offending family instances, the zoom is nearly instantaneous.

Unfortunately, it is difficult to isolate these family instances. I am hoping there is a simple way to check families using the API, instead of the rote manual inspection method I have relied on so far.

Do you think you could bang something together on this? I’ve got another large customer dataset to wade through, and was hoping for some help!

Answer: This is not at all hard to do. Here is a description of an algorithm that achieves what you need:

• Select all family instances.
• For each instance, open the corresponding family definition.
• Within the family definition, list all imported symbols.

We could also select the families themselves directly, without going over the instances first. I chose not to do so in the code presented below, because then we have to deal with various built-in families that are not actually used and we are not interested in anyway.

Here is the approach I have taken in more detail. I added an additional step to ensure every family is processed only once, even if multiple family instances refer to it. To achieve this, I create a dictionary mapping the family name to the family, and insert the families used by the family instances only if not already present. This way, I can later also process the families in alphabetical order, to make it easier to analyse the report produced. In-place families cannot be opened for editing, so we need to skip those. I am currently not aware of any way to examine their contents. Here are the detailed steps:

• Select all family instances.
• For each instance, determine its family.
• Add an entry to the family dictionary, if not already present.
• Sort the family dictionary keys.
• Open each non-in-place family and search for ImportInstance elements.
• List the total count and symbol names of all import instances found.

I added a new command class CmdImportsInFamilies to implement this functionality. Here is the source code of its Execute method:

public CmdResult Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  List<Element> instances = new List<Element>();
  doc.get_Elements( typeof( FamilyInstance ),
    instances );
 
  Dictionary<string, Family> families
    = new Dictionary<string, Family>();
 
  foreach( FamilyInstance i in instances )
  {
    Family family = i.Symbol.Family;
    if( !families.ContainsKey( family.Name ) )
    {
      families[family.Name] = family;
    }
  }
 
  List<string> keys = new List<string>(
    families.Keys );
 
  keys.Sort();
 
  foreach( string key in keys )
  {
    Family family = families[key];
    if( family.IsInPlace )
    {
      Debug.Print( "Family '{0}' is in-place.", key );
    }
    else
    {
      Document fdoc = doc.EditFamily( family );
 
      List<Element> imports = new List<Element>();
      fdoc.get_Elements( typeof( ImportInstance ),
        imports );
 
      int n = imports.Count;
 
      Debug.Print(
        "Family '{0}' contains {1} import instance{2}{3}",
        key, n, Util.PluralSuffix( n ),
        Util.DotOrColon( n ) );
 
      if ( 0 < n )
      {
        foreach( ImportInstance i in imports )
        {
          Debug.Print( "  '{0}'", i.ObjectType.Name );
        }
      }
    }
  }
  return CmdResult.Failed;
}

As usual, we return Failed when not modifying the database in any way, so that Revit understands that no changes were made to the project and no dirty flags need to be set.

I expect that this approach may need some tweaking to achieve the exact functionality you require, but I hope it provides a useful starting point at least.

After some initial testing, Martin came up with two requests for improvement:

• One thing I’m wondering about is that a family can have families nested in it. Have you considered that?
• In the attached project, the ‘Duplex Receptacle’ family has a nested ‘Annotation Symbol’ called ‘Duplex Annotation’. That ‘Duplex Annotation’ has a DWG nested in it. How can one inspect the annotation symbol for imports?

The initial solution above does indeed not take into account nested families.

Regarding the annotation symbols, we can in fact access the families used by them by making use of the property sequence AnnotationSymbol > AsFamilyInstance > Symbol > Family and then proceeding in the same way as for standard family symbols.

In order to adapt the code to support these two enhancements, I implemented two separate helper methods:

• GetFamilies to retrieve all families used by the family instances and annotation symbols in the given document and return a dictionary mapping the family name to the corresponding family object.
• ListImportsAndSearchForMore to list all import instances in all the given families, retrieve nested families within them, and recursively search in them as well.

Here is the source code for GetFamilies, taking an input document argument and returning a dictionary as described:

Dictionary<string, Family> GetFamilies( Document doc )
{
  Dictionary<string, Family> families
    = new Dictionary<string, Family>();
 
  List<Element> instances = new List<Element>();
  doc.get_Elements( typeof( FamilyInstance ),
    instances );
 
  foreach ( FamilyInstance i in instances )
  {
    Family family = i.Symbol.Family;
    if ( !families.ContainsKey( family.Name ) )
    {
      families[family.Name] = family;
    }
  }
 
  List<Element> annotations = new List<Element>();
  doc.get_Elements( typeof( AnnotationSymbol ),
    annotations );
 
  foreach ( AnnotationSymbol a in annotations )
  {
    Family family = a.AsFamilyInstance.Symbol.Family;
    if ( !families.ContainsKey( family.Name ) )
    {
      families[family.Name] = family;
    }
  }
  return families;
}

The two loops collect all family instances and annotation symbols and determine their families, respectively.

Here is the source code for ListImportsAndSearchForMore. Besides the input document argument and the dictionary of all families to list and explore further recursively, it also takes an argument indicating the recursion level, which is used to indent the output report appropriately according to the nesting level of the nested families:

void ListImportsAndSearchForMore(
  int recursionLevel,
  Document doc,
  Dictionary<string, Family> families )
{
  string indent
    = new string( ' ', 2 * recursionLevel );
 
  List<string> keys = new List<string>(
    families.Keys );
 
  keys.Sort();
 
  foreach ( string key in keys )
  {
    Family family = families[key];
 
    if ( family.IsInPlace )
    {
      Debug.Print( indent
        + "Family '{0}' is in-place.",
        key );
    }
    else
    {
      Document fdoc = doc.EditFamily( family );
 
      List<Element> imports = new List<Element>();
      fdoc.get_Elements( typeof( ImportInstance ),
        imports );
 
      int n = imports.Count;
 
      Debug.Print( indent
        + "Family '{0}' contains {1} import instance{2}{3}",
        key, n, Util.PluralSuffix( n ),
        Util.DotOrColon( n ) );
 
      if ( 0 < n )
      {
        foreach ( ImportInstance i in imports )
        {
          Debug.Print( indent
            + "  '{0}'", i.ObjectType.Name );
        }
      }
 
      Dictionary<string, Family> nestedFamilies
        = GetFamilies( fdoc );
 
      ListImportsAndSearchForMore(
        recursionLevel + 1, fdoc, nestedFamilies );
    }
  }
}

Using these two helper functions, the source code for the mainline of the Execute method is reduced to very little:

public CmdResult Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  Dictionary<string, Family> families
    = GetFamilies( doc );
 
  ListImportsAndSearchForMore( 0, doc, families );
 
  return CmdResult.Failed;
}

Running this in a project containing one family with an import symbol and another family with nested families within it produces the following output in the debug output window displayed by Debug > Windows > Output:

Family 'Family1' contains 1 import instance:
  'xr.dwg'
Family 'myFamily3' contains 0 import instances.
  Family 'M_Rectangular Column' contains 0 import instances.
  Family 'myFamily1' contains 0 import instances.
    Family 'M_Rectangular Column' contains 0 import instances.
  Family 'myFamily2' contains 0 import instances.
    Family 'M_Rectangular Column' contains 0 import instances.

In another project containing an annotation symbol with a nested family with an import symbol, it produces the following:

Family 'Duplex Receptacle' contains 0 import instances.
  Family 'Duplex Annotation' contains 1 import instance:
    'star.dwg'

Here is version 1.1.0.33 of the complete Visual Studio solution with the new command.

Parameter Binding Performance

Here is a short but important question that has come up repeatedly concerning the performance of parameter bindings.

Question: There is a big problem in the early versions of Revit 2009 with the performance of the Document ParameterBindings property, for example in the last line of the following code:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
BindingMap bindingMap = doc.ParameterBindings;

The last statement takes a huge amount of time to execute, in the order of minutes. Are there any known solutions for this?

Answer: Good news: this performance delay was analysed and reported by Saikat Bhattacharya and fixed in the Revit 2009 Web Update 3. The issue is mentioned in the associated PDF file containing the list of enhancements:

API Enhancements

• Parameter binding performance has been improved.
• The JoinType method has been implemented for the LocationCurve of structural members.
• Mullion LocationCurves are now accessible through the API.
• External programs may now suppress VSTA startup warning messages.
• The built-in parameter MATERIAL_PARAM_TRANSPARENCY now returns the correct set value.

So all you need to do is install the updated version of Revit 2009 and the problem disappears. Many thanks to Saikat for pointing this out.

Converting to Filters

This is a follow-up on the category comparison topic we brought up during the Revit Structure API training in Verona, Italy. We first ran into a language problem in the Revit SDK FrameBuilder sample and fixed that by converting the language dependent category comparison code to a language independent version. Stefano Carradore did not let it rest at that but went one step further and converted the old-fashioned and ineffective 2008-style iteration to a more effective style making use of the 2009-style API filtering functionality.

As noted in the discussion of the category comparison, the FrameBuilder sample works with structural beams and framing elements. It implements a FrameData class which defines an Initialize() method to set up internal collections of column, beam and brace symbols. They are sorted into different lists depending on their type, which is determined by comparing the category names. In the original SDK sample, the iteration is performed over all Revit elements. It picks out all the Level elements on one hand, and the structural framing and columns on the other. The levels are identified by their class, i.e. System.Type, and the structural elements by their category name. We already showed how to convert the category name comparison to a comparison of the category element id to remove the language dependence, which was preventing the code from running on the Italian version of Revit. Still, the 2008-style iteration over the entire collection of all Revit elements remains extremely inefficient.

In Stefano's new implementation, we make use of two separate API filters to extract the levels and the structural elements. This has the additional advantage of being intrinsically language independent.

Here is the original code:

ElementIterator itor
  = m_commandData.Application.ActiveDocument.Elements;

itor.Reset();
while (itor.MoveNext())
{
  object obj = itor.Current;
 
  // add level to list
  Level aLevel = obj as Level;
  if (null != aLevel)
  {
    m_levels.Add(aLevel.Elevation, aLevel);
    continue;
  }
 
  // get Family to get FamilySymbols
  Family aFamily = obj as Family;
  if (null == aFamily)
  {
    continue;
  }
 
  foreach (FamilySymbol symbol in aFamily.Symbols)
  {
    if (null == symbol.Category)
    {
      continue;
    }
 
    // add symbols to lists according to category name
    string categoryName = symbol.Category.Name;
    if ("Structural Framing" == categoryName)
    {
      m_beambracesSymbolsMgr.AddSymbol(symbol);
    }
    else if ("Structural Columns" == categoryName)
    {
      m_columnSymbolsMgr.AddSymbol(symbol);
    }
  }
}

We replace this code by two separate API filters. We could also use three filters, replacing the loop sorting the structural elements into the two separate collections by two separate dedicated filters, one each for columns and framing elements:

List<Element> a = new List<Element>();

doc.get_Elements( typeof( Level ), a );
 
foreach( Level lev in a )
{
  m_levels.Add( lev.Elevation, lev );
}
 
a.Clear();

Autodesk.Revit.Creation.Filter cf
  = app.Create.Filter;
 
Filter filterSymbols
  = cf.NewTypeFilter( typeof( FamilySymbol ) );

Filter filterCols
  = cf.NewCategoryFilter( bipColumn );

Filter filterFram
  = cf.NewCategoryFilter( bipFraming );

Filter filterStruct
  = cf.NewLogicOrFilter( filterCols, filterFram );

Filter filter
  = cf.NewLogicAndFilter( filterSymbols, filterStruct );
 
doc.get_Elements( filter, a );
 
foreach( FamilySymbol symbol in a )
{
  ElementId categoryId = symbol.Category.Id;
 
  if( idFraming.Equals( categoryId ) )
  {
    m_beambracesSymbolsMgr.AddSymbol( symbol );
  }
  else if( idColumn.Equals( categoryId ) )
  {
    m_columnSymbolsMgr.AddSymbol( symbol );
  }
}

When filtering only for the System.Type FamilySymbol without the additional check for the structural categories, our sample project was returning over 500 family symbols. Adding the category filters reduced this number to 40.

Here is the updated source code for FrameData.cs with the three different variants enclosed in conditional compilation pragmas.

Element Caching

Here is a question from Julien Duprat of Vertice:

Question: I would like to know the best practises for data caching. This topic is mentioned in your tutorial on "Ten Steps for enhancing your Revit add-in". Specifically, I wonder:

• How to put the elements in a static List<Element> of cached elements?
• How to refresh this list?

Answer: We do not have any official recommendations from the API or development team, so it is more a question of finding out what works best.

The one thing to be aware of is that it is currently not possible to keep track of the exact state of the Revit database, because we are still lacking any element level events. We can request notification when certain events occur at an application or document level, such as application start-up or shutdown and document creation, open, save, and close. There is no notification about adding, deleting or modifying individual elements, though.

Another point is that this issue is much less important in Revit 2009 than it was in 2008. In 2008, we did not yet have the element filtering API. That meant that it was extremely expensive to retrieve a specific set of elements from the database, because the application basically had to iterate over the entire database and filter out the elements it needed itself. To avoid repeating this lengthy iteration several times, it was important to identify all required elements up front and perform the entire iteration for all required elements only once and in one single go. In 2009, with element filtering, this is not longer the case. We now have full support from the Revit API for a highly efficient and optimised selective access, and an application can repeatedly query the database for different sets of specific elements with hardly any overhead. Therefore, the need for caching elements is drastically reduced.

The first part of your question is very easy: to add an element to a generic list, simply call the Add method.

As explained, the second part is more difficult. I would suggest that you update the list every time you need to make use of it.

Parameter Modification Performance

I just finished the third and final of my presentations at AU 2008 and had a great time doing so, with enthusiastic and friendly audiences. For a live impression of the atmosphere here, don't miss having a look at Kean's posts on his arrival, first day, and the exhibit hall at AU.

Meanwhile I noticed the following interesting issue on parameter modification performance raised by Michael Raps of the Institut 4D-Technologies and DataSpaces at the Fachhochschule Nordwestschweiz and being explored by Saikat Bhattacharya of our Bangalore office.

Modifying multiple parameters sometimes takes an inordinate amount of time. I noticed something similar myself once running a command which modified parameters on HVAC air terminals. Executing this command in Revit Architecture worked fine and fast, but it took an order of magnitude longer to execute in Revit MEP, because Revit MEP was continuously recalculating and updating the entire duct system every time one of the parameters changed.

Michael's issue is simpler and does not involve any complex regeneration of the entire system by Revit. The problem was that executing the following simple code in a model using a specific custom family took extremely long:

// Start measurement
int millis = Environment.TickCount;
 
// Set some values
Parameter p = instance.get_Parameter("Breite");
p.Set(500);
 
// Set some Booleans
p = instance.get_Parameter("Füsse");
p.Set(1);
 
p = instance.get_Parameter("Sockel");
p.Set(1);
 
p = instance.get_Parameter("Rille");
p.Set(1);
 
// Set some strings
p = instance.get_Parameter("Bezeichnung Deutsch");
p.Set("Deutsche Bezeichnung");
 
p = instance.get_Parameter("Bezeichnung Englisch");
p.Set("English description");
 
p = instance.get_Parameter("Comments");
p.Set("A comment");
 
millis = Environment.TickCount - millis;
MessageBox.Show( 
  millis + "Millis to set 9 parameters. " +
  " (about " + millis / 9.0 + " millis per param)" );

Michael made use of the profiling functionality provided by the dotTrace profiler for .NET to create the following execution time analysis:

One issue involved here is a known behaviour with parameter bindings and was fixed in the web update version of Revit 2009, so the first step is to ensure that you have the latest build. Even after this update, the performance was still pretty slow:

Saikat then discovered that replacing the custom family by a simpler RFA file such as a rectangular column family caused it to work like a flash. Thus, the delay is partially due to the dataset being used, in this case the family file, and not entirely caused by the Parameter.Set() API call. This is one detail to keep in mind when you run into performance issues setting parameters.