The Building Coder

Document Elements

We have already used the Document.Elements property a couple of hundred times in previous posts to this blog, so this explanation is rather belated, but addresses a question that does keep on popping up from time to time anyway:

Question: How can I access the Document.Elements property in C#?

The Revit help document lists the property named Document.Elements, stating that it is an overloaded property providing access to a set of elements from the document. The overloads are listed as

• Elements: Provides access to all elements within the document.
• Elements( Filter ): Provides access to all elements which satisfy specified filter.
• Elements( Type ): Provides access to all elements of specified type.
• Elements( Filter, ElementArray ): Collects all elements which satisfy specified filter.
• Elements( Filter, ICollection of Element ): Collects all elements which satisfy specified filter.
• Elements( Type, ElementArray ): Collects all elements which satisfy specified type.
• Elements( Type, ICollection of Element ): Collects all elements which satisfy specified type.

However, when I try to access these properties in C#, the Visual Studio compiler reports an error and says that they do not exist. How can I access these properties in C#?

Answer: You can look at the C# source code generated automatically by the definition of the Document class by Visual Studio, by positioning the cursor over the Document type and pressing F12. This shows a completely different list of overloads:

• public ElementIterator Elements;
• public ElementIterator get_Elements( Filter );
• public ElementIterator get_Elements( Type );
• public int get_Elements( Filter, ElementArray );
• public int get_Elements( Filter, ICollection );
• public int get_Elements( Type, ElementArray );
• public int get_Elements( Type, ICollection );

As you can see, only the Elements property with no filter or type argument is available using the name given in the help file. The other Document.Elements members are considered to be methods, not properties, and have therefore been automatically decorated with the accessor prefix "get_". To call them, you need to prepend "get_" and obviously also provide the required arguments.

Question: How can I access the Document.Elements property in VB?

I have converted some C# sample the code to VB but have an error with a function in the line

  m_doc.getElements(viewFilter, views) 

The error states that .GetElements is not a member of Autodesk.Revit.Document, although I have defined m_doc as an Autodesk.Revit.Document.

Answer: You can use the Visual Studio Intellisense functionality or the object browser to determine the real name of the method you are trying to invoke in whatever language you prefer to use.

The method or property you are accessing is called Elements in the Revit API help. In C#, it is accessed using the call

  m_doc.get_Elements(viewFilter, views);

In VB, you have to drop the "get_" prefix, so the call is

  m_doc.Elements(viewFilter, views)

Reply: Thanks for the response. I did try with Elements, but this causes an error saying "property access must assign to the property or use its value", as it is returning an Integer. This problem goes away if I use

  Dim i as Integer = m_doc.getElements(viewFilter, views)

What are we using the return value from this line for anyway?

Answer: Oops, yes, right you are. The return value of these properties is the number of elements matching the specified criteria.

In VB, this is a read-only property, and the VB syntax requires you to make use of it as such. This means that you must read the value returned by the property, regardless of whether you make use of it or not.

Maybe this is part of the reason why these members are considered methods instead of properties in C#. In C#, you are not forced to read the return value, but you can, if you like.

Store Project Data

We recently discussed storing structured data in a Revit file, and received a number of very helpful additional comments on the topic. To store custom application data in a Revit project, one needs to attach a shared parameter to some Revit elements. As we have seen in the discussion on model group shared parameters, almost any element can be used to host the shared parameter. Here is a common related question:

Question: Where can I store project-wide information in a Revit file, data which is not related to any specific individual element?

Answer: First of all, there is no need to separate the two issues of element-specific versus global data, because the only way to store application data in Revit is to use shared parameters on certain elements. Luckily, there is one object which occurs exactly once in the entire project and therefore constitutes a suitable repository for global document data, also known as a singleton object: the project information or ProjectInfo element. It can be retrieved using Revit 2009 filtering by searching for the "Project Information" category with the built-in category OST_ProjectInformation. This is discussed in the standard Revit programming introduction presentation and demonstrated by the labs 4-4-1 and 4-4-2 in the Revit API introduction labs.

The ProjectInfo singleton element is not present in a family file, so we have to resort to some other method in that case.

Per-document shared parameter in a family document

Question: How can we add a per-document shared parameter to a family document? The lab 4-4-1 contains code to create and bind shared parameters to the Project Information category, or basically to anything which appears as a singleton in the document. How can we implement the same for a family document? It does not contain a Project Information element.

Answer: Looking at a new family file using RvtMgdDbg, I can see one likely candidate, the ProjectUnit object. I imagine that element also only occurs exactly once. There are some other elements which may or may not also be unique: the default material, the front view, the basic reference level, the solid fill FillPattern, the Work Plane Grid element, etc. I suggest you pick an element, any element. Build a filter to select all such elements. Include an assertion to verify that exactly one is returned in all cases. Any element will do, it just has to be easily selectable and unique.

Actually, in a family document, you can probably also use a hidden family parameter instead of attaching the data to any specific element contained within the document.

View Sketch Plane

Some views provide a sketch plane, others do not. In particular, the section views do not. Here is a little exploration into this subject prompted by the following question from Toste Wallmark of Tecton Limited:

Question: I'm trying to get the SketchPlane property of currently active view, which is a section view. However, it returns null. Do I need to manually create a sketch plane for section views? Other types of views, like floor plans, do correctly return a SketchPlane object.

Answer: I implemented a little dedicated sample application to test your assertion, and I can reproduce what you say in the sample projects that I have looked at so far.

I would recommend to always check whether the sketch plane returned from a view is null or not. In case it is null, you will obviously have to create your own. You can do so using the view origin and direction. These values are always available from the corresponding properties on the view object, even though the view plane is null.

Here is the result of searching for all document elements that are of the View class or one of its five derived classes. Looking at a separate listing of all database elements, I noticed that many of the view related objects occur in pairs, like the elements used for level 1 and 2 below with the element id pairs (13073, 13077) and (15915, 15919). In the other cases, the object type of only one of the two related objects is View, whereas the other is simply a Revit Element and thus does not appear in this list:

I also print out this list to the Visual Studio debug output window. The overly long lines can be seen by copying this text to an editor:

List of document views' sketch planes: 

View [3651] Project View origin (0,0,0) direction (0,-1,0): 
ViewPlan [13073] Level 1 origin (0,0,0) direction (0,0,1): Level 1 plane origin (0,0,0), plane normal (0,0,1)
ViewPlan [13077] Level 1 origin (0,0,0) direction (0,0,1): Level 1 plane origin (0,0,0), plane normal (0,0,1)
ViewPlan [15915] Level 2 origin (0,0,0) direction (0,0,1): Level 2 plane origin (0,0,13.12), plane normal (0,0,1)
ViewPlan [15919] Level 2 origin (0,0,0) direction (0,0,1): Level 2 plane origin (0,0,13.12), plane normal (0,0,1)
View [29152] North origin (-1.04,84.1,3.94) direction (0,1,0): 
View [29193] East origin (84.12,-2.54,3.94) direction (1,0,0): 
View [29214] West origin (-84.13,-2.42,3.94) direction (-1,0,0): 
View [29233] South origin (-1.08,-84.12,3.94) direction (0,-1,0): 
ViewPlan [29273] Site origin (0,0,0) direction (0,0,1): Level 1 plane origin (0,0,0), plane normal (0,0,1)
View [92030] System Browser origin (0,0,0) direction (0,0,1): 
View [138046] Section 1 origin (-20.55,2.78,13.12) direction (-1,0,0): 

Note that this list includes a view object for the system browser, which obviously has no sketch plane at all. It still returns valid values for the view origin and direction.

Here are the utility methods used by the external command which generates this list:

static string RealString( double a )
{
  return a.ToString( "0.##" );
}
 
static string PointString( XYZ p )
{
  return string.Format( 
    "({0},{1},{2})",
    RealString( p.X ), 
    RealString( p.Y ),
    RealString( p.Z ) );
}
 
static string PlaneString( Plane p )
{
  return string.Format( 
    "plane origin {0}, plane normal {1}",
    PointString( p.Origin ), 
    PointString( p.Normal ) );
}
 
static Filter OrType( 
  Filter f, 
  Type t, 
  Autodesk.Revit.Creation.Filter cf )
{
  Filter f2 = cf.NewTypeFilter( t );
  return cf.NewLogicOrFilter( f, f2 );
}

Here is the code of the external command Execute method:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
View activeView = doc.ActiveView;
 
Autodesk.Revit.Creation.Filter cf 
  = app.Create.Filter;
 
Filter f1 = cf.NewTypeFilter( typeof( View ) );
Filter f2 = OrType( f1, typeof( View3D ), cf );
Filter f3 = OrType( f2, typeof( ViewDrafting ), cf );
Filter f4 = OrType( f3, typeof( ViewPlan ), cf );
Filter f5 = OrType( f4, typeof( ViewSection ), cf );
Filter f6 = OrType( f5, typeof( ViewSheet ), cf );
 
List<RvtElement> views = new List<RvtElement>();
doc.get_Elements( f6, views );
 
Debug.Assert( 0 < views.Count, 
  "expected document to have at leat one view" );
 
string msg 
  = "List of document views' sketch planes: " 
  + Environment.NewLine;
 
foreach( View view in views )
{
  msg += string.Format( 
    "{0}{1} [{2}] {3} origin {4} direction {5}: ", 
    Environment.NewLine, 
    view.GetType().Name, 
    view.Id.Value, 
    view.Name,
    PointString( view.Origin ),
    PointString( view.ViewDirection ) );
 
  SketchPlane sketch = view.SketchPlane;
  msg += ( null == sketch ) 
    ? "<null sketch>" 
    : sketch.Name + " " + PlaneString( sketch.Plane );
}
Debug.Print( msg );
WinForms.MessageBox.Show( msg, "View Sketch Planes" );
return IExternalCommand.Result.Failed;

Note that specifying a type filter when calling the document get_Elements method does not return derived types, only the specific type given. Since I wish to retrieve all types derived from the View class as well as base class View elements, I need to create a Boolean expression or'ing together all of them. For this purpose, I invented a nice new little OrType method for succinctly or'ing together a sequence of type filters.

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.

Selecting Model Elements

This morning I woke up really early. The hotel clock was set incorrectly, so when I woke up and looked at it, I thought I was much too late for my meeting. I jumped out of bed, grabbed and packed all my things and ran out of the room to the lobby, where I noticed that it seemed rather quiet outside and the light was very soft and special in the early morning. Up here in the north it does get light very early, though. At least I noticed my error before actually getting out into the street. Now I am unable to sleep, sitting in bed and writing this post.

The Revit API Introduction Lab 2-2 demonstrates how to select all model elements, i.e. elements which are visible on the graphics screen and represent physical parts in the building model. This lab is part of the sample code used to explain the basics of programming Revit in the Revit programming webcast. When updating this code for Revit 2010, I noticed that one change has occurred in Revit which causes this command to return incorrect results. First let us have a look at the original version which worked properly in Revit 2009, and then discuss the changes I made for 2010.

In 2009, we used the following helper method to select all model elements:

public static ElementSet GetAllModelElements(
  Application app )
{
  ElementSet elems = app.Create.NewElementSet();

  Geo.Options opt = app.Create.NewGeometryOptions();

  ElementIterator iter = app.ActiveDocument.Elements;
  while( iter.MoveNext() )
  {
    Element e = iter.Current as Element;

    if( !( e is Symbol || e is FamilyBase ) )
    {
      if( null != e.Category )
      {
        if( null != e.get_Geometry( opt ) )
        {
          elems.Insert( e );
        }
      }
    }
  }
  return elems;
}

It iterates over all elements in the active document and checks their class, category and geometry content to select the model elements. The selected elements are stored in a new element set, which is returned to the caller.

When asking the elements for their geometry, a geometry options instance must be provided. This argument cannot be null. Otherwise, an exception will be thrown. However, its detail level property and other properties may be left uninitialized.

The iterator type can be specified as either ElementIterator or IEnumerator. The iterator returned by the document Elements property is in fact an ElementIterator instance. This class is derived from the IEnumerator interface, and we only make use of the base class functionality, so an IEnumerator instance could be used just as well.

All the objects returned by the iterator are Autodesk.Revit.Element instances. It would be nice to know that we only need to check for certain specific types of objects, derived from the Autodesk.Revit.Element class, for example FamilyInstance and HostObject classes. Unfortunately, some Revit building model objects such as stairs are still represented in the API using the generic Autodesk.Revit.Element class, so this is not possible. Instead, we use the inverse approach of eliminating certain element types which are not used for building model objects, namely the Symbol and FamilyBase classes.

All building model objects have a valid category and non-empty geometry, so those properties can be used reliably.

However, in Revit 2010, running the same code suddenly returns a number of unexpected objects, even in an empty model.

Legend Component Geometry

The reason for the change in behaviour in Revit 2010 is that legend component objects now also return geometry. Since they are represented by Autodesk.Revit.Element instances, are not Symbol or ElementBase instances, and also have a valid category, they pass all the filters applied above in spite of not being model objects. Here is a list of the legend component elements returned in Revit 2010 in an empty model (copy to an editor to see the full line length):

There are 50 model elements:
  Name=Basic Wall : Generic - 150mm (Floor Plan); Category=Legend Components; Id=137075
  Name=Basic Wall : Interior - 138mm Partition (1-hr) (Floor Plan); Category=Legend Components; Id=137076
  Name=Basic Wall : Exterior - Brick and Block on Mtl. Stud (Floor Plan); Category=Legend Components; Id=137077
  Name=Basic Roof : Generic Roof - 300mm (Section); Category=Legend Components; Id=137078
  Name=Basic Roof : Generic Roof - 750mm (Section); Category=Legend Components; Id=137079
  Name=Basic Roof : Generic Roof - 500mm (Section); Category=Legend Components; Id=137080
  Name=Floor : Generic Floor - 400mm (Section); Category=Legend Components; Id=137081
  Name=Basic Ceiling : Generic (Section); Category=Legend Components; Id=137082
  Name=Basic Wall : Generic - 200mm (Floor Plan); Category=Legend Components; Id=137083
  Name=Basic Wall : Generic - 250mm (Floor Plan); Category=Legend Components; Id=137084
  Name=Basic Wall : Generic - 300mm (Floor Plan); Category=Legend Components; Id=137085
  Name=Basic Wall : Generic - 375mm (Floor Plan); Category=Legend Components; Id=137086
  Name=Basic Wall : Generic - 300mm Masonry (Floor Plan); Category=Legend Components; Id=137087
  Name=Basic Wall : Generic - 200mm CMU (Floor Plan); Category=Legend Components; Id=137088
  Name=Basic Wall : Generic - 150mm Masonry (Floor Plan); Category=Legend Components; Id=137089
  Name=Basic Wall : Exterior - EIFS on Mtl Stud (Floor Plan); Category=Legend Components; Id=137090
  Name=Basic Wall : Generic - 90mm Brick (Floor Plan); Category=Legend Components; Id=137091
  Name=Basic Wall : Interior - 79mm Partition (1-hr) (Floor Plan); Category=Legend Components; Id=137092
  Name=Basic Wall : Interior - 123mm Partition (1-hr) (Floor Plan); Category=Legend Components; Id=137093
  Name=Basic Wall : Interior - 135mm Partition (2-hr) (Floor Plan); Category=Legend Components; Id=137094
  Name=Basic Wall : Interior - 126mm Partition (2-hr) (Floor Plan); Category=Legend Components; Id=137095
  Name=Basic Wall : Exterior - Brick on CMU (Floor Plan); Category=Legend Components; Id=137096
  Name=Curtain Wall (Floor Plan); Category=Legend Components; Id=137097
  Name=Floor : Wood Joist 220mm - Wood Finish (Section); Category=Legend Components; Id=137098
  Name=Floor : Steel Bar Joist - VCT on LW Concrete  (Section); Category=Legend Components; Id=137099
  Name=Basic Roof : Wood Rafter 184mm - Asphalt Shingles (Section); Category=Legend Components; Id=137100
  Name=Basic Roof : Steel Truss - Insulation on Metal Deck- EPDM (Section); Category=Legend Components; Id=137101
  Name=Basic Wall : Foundation - 300mm Concrete (Floor Plan); Category=Legend Components; Id=137102
  Name=Basic Wall : Retaining - 300mm Concrete (Floor Plan); Category=Legend Components; Id=137103
  Name=Basic Wall : Generic - 200mm - Filled (Floor Plan); Category=Legend Components; Id=137104
  Name=Basic Roof : Generic Roof - 300mm - Filled (Section); Category=Legend Components; Id=137105
  Name=Floor : Generic Floor - 400mm - Filled (Section); Category=Legend Components; Id=137106
  Name=Compound Ceiling : 600 x 1200mm grid (Section); Category=Legend Components; Id=137107
  Name=Compound Ceiling : 600 x 600mm grid (Section); Category=Legend Components; Id=137108
  Name=Compound Ceiling : GWB on Mtl Stud (Section); Category=Legend Components; Id=137109
  Name=Roof Soffit : Generic - 300mm (Section); Category=Legend Components; Id=137110
  Name=Curtain Wall : Exterior Glazing (Floor Plan); Category=Legend Components; Id=137111
  Name=Curtain Wall : Storefront (Floor Plan); Category=Legend Components; Id=137112
  Name=Basic Wall : Exterior - Brick on Mtl. Stud (Floor Plan); Category=Legend Components; Id=137113
  Name=Stacked Wall : Exterior - Brick Over Block w Metal Stud (Floor Plan); Category=Legend Components; Id=137114
  Name=Basic Wall : Exterior - Block on Mtl. Stud (Floor Plan); Category=Legend Components; Id=137115
  Name=Foundation Slab : 150mm Foundation Slab (Section); Category=Legend Components; Id=137116
  Name=; Category=Legend Components; Id=137117
  Name=; Category=Legend Components; Id=137118
  Name=; Category=Legend Components; Id=137119
  Name=; Category=Legend Components; Id=137120
  Name=; Category=Legend Components; Id=137121
  Name=; Category=Legend Components; Id=137122
  Name=; Category=Legend Components; Id=137123
  Name=; Category=Legend Components; Id=137124

These legend components are the keepers of the images displayed in the type preview dialog. The graphical previews are new in 2010 and so the presence of these elements is also new. The exposure of their geometry to the API is not intentional and may be removed again in future. Their only function is to create and hold that one image, and the user has no other way to interact with them.

How can we improve our filter to eliminate these unwanted elements?

Since the legend components have a valid category, we could simply add that additional criterion to the list of properties that we are checking, for instance like this:

const string _CategoryNameLegendComponents
  = "Legend Components";

  if( !(e is Symbol)
    && !(e is FamilyBase)
    && (null != e.Category)
    && (_CategoryNameLegendComponents != e.Category.Name)
    && (null != e.get_Geometry(opt)) )
  {
    // . . .
  }

Instead of using a string comparison on the category name, we could also determine the element id of the legend component category and compare that with each candidate element id.

However, both of these options would add yet another item to an already lengthy list of checks.

A simpler option that seems to work well in the tests I have run so far is to skip checking the object type at all, and replacing it by requiring a valid level, like this:

  if( (null != e.Category)
    && (null != e.Level)
    && (null != e.get_Geometry(opt)) )

Besides being simpler and easier to understand, this check is probably also slightly more efficient. It has not been extensively tested yet, so please let me know if you discover any situations in which it fails.

Here is the current version of the Revit API introduction labs, including the new version of Lab 2-2 to select all model elements using this criterion. The labs are still in the process of being further updated and enhanced for the Revit 2010 API and its new features. All of the labs are provided in two versions, one each for C# and VB.

Filter for a Family

We already discussed the topic of family category and filtering previously, but this question keeps cropping up anyway, so here is a repetition from a slightly different point of view by Saikat Bhattacharya.

Question: I am trying to get the loaded families with a LightingFixtures category. However, I am not getting the results I expected. I used the following code:

Autodesk.Revit.Creation.Filter cf
  = app.Create.Filter;
 
Filter f1 = cf.NewTypeFilter(
  typeof( Family ) );
 
Filter f2 = cf.NewCategoryFilter(
  BuiltInCategory.OST_LightingFixtures );
 
LogicAndFilter f3 = cf.NewLogicAndFilter(
  f1, f2 );
 
List<Element> a = new List<Element>();

doc.get_Elements( f3, a );

foreach( Family f in a )
{
  Util.InfoMsg( f.Name );
}

No elements are returned from the Document using this filter. So, I retrieved all the families instead and checked if the category name of the family is "Lighting Fixtures". This is language dependant and consumes long time. How can I achieve this using filters?

Answer: As mentioned in the discussion on family category and filtering, the Family class does not implement the Category property for all family files. Therefore, you cannot use a category filter to identify family files.

If you retrieve all family files and check their category using some other means, like in you the workaround you describe, you can enhance performance and avoid the language dependence by comparing the category element id instead of its name string.

By the way, you can always manually test and interactively simulate the result of any API filter by using the Revit SDK sample ElementsFilter. For a quick test, load a lighting fixture family into a new Revit document and run this sample with a family filter selecting the lighting fixture family. The following results show the Category as blank for the Family element:

Instead of creating a filter using Family and Category, you can also change it to FamilySymbol and Category to obtain the symbols instead of the family elements. The Category property is always defined for family symbols. If you need the families, they are accessible from the symbols as well. If you simply replace typeof( Family ) by typeof( FamilySymbol ) in the definition of the filter f1 in the code above, it works fine.

List Railing Types

This is in response to a query from Berria on iterating over the railing types in the model. It is also once again about teaching how to fish, and not just feeding people, at least I hope so. If I want to list all the railing types, the best way to go is probably to define an API filter which retrieves them from the model for me. How do I design that filter? I start by opening a new model, inserting a railing, and examining it with RvtMgdDbg. There I can easily determine that its built-in category is OST_StairsRailing. Therefore, I first thought that an API filter selecting all family symbols of this category should suffice. The project browser shows me the following stair and railing symbols in my current model:

I implemented a new external command CmdListRailingTypes to test this approach, with the following code:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
CreationFilter cf = app.Create.Filter;
 
List<Element> symbols = new List<Element>();
 
BuiltInCategory bic 
  = BuiltInCategory.OST_StairsRailing;
 
Filter f1 
  = cf.NewCategoryFilter( bic );
 
Filter f2 
  = cf.NewTypeFilter( typeof( FamilySymbol ) );
 
doc.get_Elements( f, symbols );

foreach( FamilySymbol s in symbols )
{
  Debug.Print(
    "Family name={0}, symbol name={1}",
    s.Family.Name, s.Name );
}
return CmdResult.Failed;

It makes use of a new alias for CreationFilter:

using CreationFilter
  = Autodesk.Revit.Creation.Filter;

To my initial surprise, no symbols were found. I thereupon took a closer look at the symbols within the railings family in RvtMgdDbg and discovered that the category of the M_Baluster symbols is not OST_StairsRailing but OST_StairsRailingBaluster. Changing the value of the 'bic' variable to that built-in category returns some valid results:

Family name=M_Baluster - Square, symbol name=25mm
Family name=M_Baluster - Square, symbol name=20mm
Family name=M_Baluster - Round, symbol name=25mm
Family name=M_Baluster - Round, symbol name=20mm

This does still not include all the railing symbols listed in the browser, so I went back into RvtMgdDbg and searched for those as well. They were not listed in the FamilySymbol collection, but under Symbols, this time indeed with the category OST_StairsRailing.

Making use of this info, I implemented a second filter and iteration to retrieve and list Symbol objects like this:

bic = BuiltInCategory.OST_StairsRailing;
f1 = cf.NewCategoryFilter( bic );
f2 = cf.NewTypeFilter( typeof( Symbol ) );
f = cf.NewLogicAndFilter( f1, f2 );
 
doc.get_Elements( f, symbols );
 
n = symbols.Count;
 
Debug.Print( "{0}"
  + " OST_StairsRailing symbol{1}:",
  n, Util.PluralSuffix( n ) );
 
foreach( Symbol s in symbols )
{
  FamilySymbol fs = s as FamilySymbol;
 
  Debug.Print(
    "Family name={0}, symbol name={1}",
    null == fs ? "<none>" : fs.Family.Name, 
    s.Name );
}

The result of this code is somewhat surprising too. The non-family symbols that we are looking for are retrieved now, just like we hoped, and we also retrieve the family symbols that we already saw above:

6 OST_StairsRailing symbols:
Family name=M_Baluster - Square, symbol name=25mm
Family name=M_Baluster - Square, symbol name=20mm
Family name=M_Baluster - Round, symbol name=25mm
Family name=M_Baluster - Round, symbol name=20mm
Family name=<none>, symbol name=900mm Pipe
Family name=<none>, symbol name=900mm Rectangular

This goes to show several things:

• You need to explore the model.
• You may get unexpected results.

I'll just leave it at that for now.

Here is version 1.0.0.25 of the complete Visual Studio solution with the new CmdListRailingTypes command implementation.

Inserting a Beam

This is the final Verona installment, discussing the last remaining topic raised in the Revit API training in Verona the week before last, on creating new beam types and inserting beam instances through the API.

Similar to the exploration concerning columns, we explored the following topics:

• Retrieving all matching family elements in current document in order to check whether the family we are interested in is loaded.
• Exploring the results of using a FamilyFilter.
• Loading a new family, if not already present.
• Creating a new family symbol, i.e. duplicating a beam type and setting its name and dimensions.
• Inserting a new beam instance into the model.

The interesting new aspects addressed with beams compared to columns are:

• The family type parameters and the naming convention used are completely different.
• Inserting a beam instance requires using a different version of NewFamilyInstance.

We implemented a new external command CmdNewBeamTypeInstance to demonstrate the steps listed above. It is very similar to the command CmdNewColumnTypeInstance for the columns. First, we set up some constants to define the family we are interested in, its library path, the structural type and a unit conversion:

const string family_name
  = "M_Concrete-Rectangular Beam";
 
const string extension
  = ".rfa";
 
const string directory
  = "C:/Documents and Settings/All Users"
  + "/Application Data/Autodesk/RAC 2009"
  + "/Metric Library/Structural/Framing"
  + "/Concrete/";
 
const string path
  = directory + family_name + extension;
 
StructuralType stBeam
  = StructuralType.Beam;

Creating a new Beam Type

Most of the implementation of the Execute method is the same as for CmdNewColumnTypeInstance. We check whether the family we are interested in is already loaded, making use of a family filter to get all family elements in the current document. We again note that the family filter returns both the symbols contained within the family and the family itself. The family element itself is stored in the variable 'f', and its symbols are simply listed. In real life, we would probably eliminate the symbols by creating a Boolean 'and' filter and filtering for the Family class as well as the family name. If the family was not already loaded, then 'f' remains null, and we load it with the LoadFamily method. It would also be sufficient to load one single symbol from the family, since we just need one single symbol 's' in order to call its Duplicate method. Any one will do, so we simply select the first one. When duplicating it, we simultaneously define the new symbol name. We list all its parameters, set the new type's dimensions, and demonstrate that we can change its name at a later stage as well if desired:

s.get_Parameter( "b" ).Set(
  Util.MmToFoot( 500 ) );
 
s.get_Parameter( "h" ).Set(
  Util.MmToFoot( 1000 ) );

s.Name = "Nuovo simbolo due";

The names of the dimension parameters we are interested in for the beam are named 'b' and 'h'. The column class that we examined used a completely different naming convention, with full names and upper-case initial letters, e.g. 'Width' and 'Depth'. This just goes to show that families are user defined and every family can use different conventions.

The new beam and column types appear like this in the Revit project browser:

To follow the standard Revit type naming conventions, we would normally include the new type dimensions in its name, like the existing types do.

Creating FamilyInstance Objects

We did some experiments in order to place an instance of our new symbol in the model. First we verified that it is possible to insert a beam, which normally uses a location line, by specifying only a location point:

XYZ p = XYZ.Zero;
doc.Create.NewFamilyInstance( p, s, nonStructural );

We can also place it with just a point and a direction:

XYZ p = XYZ.Zero;
XYZ q = app.Create.NewXYZ( 30, 20, 20 ); // feet

FamilyInstance fi = doc.Create.NewFamilyInstance(
  p, s, q, null, nonStructural );

In both of these cases, the instance has no location line defined for it, causing it to behave rather strangely and basically be unusable, e.g. it cannot be selected.

It is also possible to place it on a level, but lacking a location line, this version is also not really useful:

List<Element> levels = new List<Element>();
doc.get_Elements( typeof( Level ), levels );
Debug.Assert( 0 < levels.Count,
  "expected at least one level in model" );
 
Level level = levels[0] as Level;
 
fi = doc.Create.NewFamilyInstance(
  line, s, level, nonStructural );

These various attempts led us to realise that we really do need to define a location line for the beam. We also verified that we must specify a structural type. Specifying a non-structural type means that no beam is created, and results in a null family instance. So this is the final working version for inserting a valid instance of a beam with sloped location line:

XYZ p = XYZ.Zero;
XYZ q = app.Create.NewXYZ( 30, 20, 20 ); // feet

Line line = app.Create.NewLineBound( p, q );

FamilyInstance fi = doc.Create.NewFamilyInstance(
  line, s, null, stBeam );

Here is an image showing the result of running the two new commands CmdNewBeamTypeInstance and CmdNewColumnTypeInstance, which insert one instance each of the of the new beam and column types:

By the way, if you have any questions regarding the use of NewFamilyInstance and especially the choice of the correct overload to use for specific situations, the first place to look is in the Revit 2009 API Developer Guide section 11.3.4 on Creating FamilyInstance Objects. That document contains the most complete and up-to-date description of the topic. That section was also provided temporarily as a stand-alone SDK document named Guide to placing Family Instances with the API.doc This document provides a roadmap on how to create different categories of family instances using the API. Typically these instances are created using one of the eight overloads of the Autodesk.Revit.Creation.Document method NewFamilyInstance. The choice of which overload to use depends not only on the category of the instance, but also other characteristics of the placement, such as whether it should be hosted, placed relative to a reference level, or placed directly on a particular face. The details are included in a table. Instances of some family types are better created through methods other than NewFamilyInstance and are listed in a second table.

Here is version 1.0.0.24 of the complete Visual Studio solution with the new CmdNewBeamTypeInstance command implementation.

Inserting a Column

Here I continue the discussion of another of the topics that were raised in the Revit API training in Verona last week, on creating new column types and inserting column instances through the API.

We explored the following topics:

• Retrieving all family elements in current document in order to check whether the family we are interested in is loaded.
• Exploring the results of using a FamilyFilter.
• Loading a new family, if not already present.
• Creating a new family symbol, i.e. duplicating a type and setting its name and dimensions.
• Inserting a new column instance into the model.

We implemented a new external command CmdNewColumnTypeInstance to demonstrate these steps. First, we set up some constants to define the family we are interested in, our library path, the structural type and a unit conversion:

const string family_name
  = "M_Rectangular Column";
 
const string extension
  = ".rfa";
 
const string directory
  = "C:/Documents and Settings/All Users"
  + "/Application Data/Autodesk/RAC 2009"
  + "/Metric Library/Columns/";
 
const string path
  = directory + family_name + extension;
 
StructuralType nonStructural
  = StructuralType.NonStructural;
 
const double _foot_to_mm
  = 25.4 * 12;

Here is the implementation of the Execute method which achieves the steps listed above:

In order to check whether the family we are interested in is already loaded, we make use of a family filter to get all family elements in the current document. If so, we store it in the variable 'f'.

The family filter returns both the symbols contained within the family and the family itself. In real life, we would probably eliminate the symbols by creating a Boolean 'and' filter and filtering for the Family class as well as the family name.

CmdResult rc
  = CmdResult.Failed;
 
Application app = commandData.Application;
Document doc = app.ActiveDocument;

List<Element> symbols = new List<Element>();
 
Filter filter = app.Create.Filter.NewFamilyFilter(
  family_name );
 
doc.get_Elements( filter, symbols );

Family f = null;
foreach( Element e in symbols )
{
  if( e is Family )
  {
    f = e as Family;
  }
  else if( e is FamilySymbol )
  {
    FamilySymbol s = e as FamilySymbol;
    Debug.Print(
      "Family name={0}, symbol name={1}",
      s.Family.Name, s.Name );
  }
}

If the family was not already loaded, then 'f' remains null, and we load it with the LoadFamily method. It would also be sufficient to load one single symbol from the family:

if( null == f )
{
  if( !doc.LoadFamily( path, ref f ) )
  {
    message = "Unable to load '" + path + "'.";
  }
}

If the loading does not succeed, 'f' is still null and we cannot proceed. Otherwise, we pick one of them for duplication and store it in the variable 's'. Any one will do, so we simply select the first one.

if( null != f )
{
  Debug.Print( "Family name={0}", f.Name );

  FamilySymbol s = null;
  foreach( FamilySymbol s2 in f.Symbols )
  {
    s = s2;
    break;
  }
  Debug.Assert( null != s,
    "expected at least one symbol"
    + " to be defined in family" );

We duplicate it using the Duplicate method, simultaneously defining the new symbol name. To find out what parameters are available for setting the new type's dimensions, we first list all of them. We set the new type's dimensions and demonstrate that we can change its name at a later stage as well if desired. By trial and error, we definitely proved that when using a localised name to set the parameter value, the specified name is case sensitive.

  Symbol s1 = s.Duplicate( "Nuovo simbolo" );
  s = s1 as FamilySymbol;

  foreach( Parameter param in s.Parameters )
  {
    Debug.Print(
      "Parameter name={0}, value={1}",
      param.Definition.Name,
      param.AsValueString() );
  }

  s.get_Parameter( "Width" ).Set(
    500 / _foot_to_mm );
 
  s.get_Parameter( "Depth" ).Set(
    1000 / _foot_to_mm );

  s.Name = "Nuovo simbolo due";

Finally, we insert an instance of our new symbol. We also tested inserting it using a non-vertical reference direction, but that is ignored for columns, because columns are inherently vertical:

  XYZ p = XYZ.Zero;
  doc.Create.NewFamilyInstance(
    p, s, nonStructural );

  rc = CmdResult.Succeeded;
}
return rc;

The next step we took was to explore the similar concepts for beams and braces, but the discussion of those steps will have to wait until some later time.

Here is version 1.0.0.23 of the complete Visual Studio solution with this new command implementation.