The Building Coder

Crop 3D View to Room

In case you have heard enough about both climbing and AU and AUv in the last few posts and would prefer to read about the Revit API and nothing but the Revit API, here is something for you. This is based on a recent case handled by Joe Ye and deals with the 3D view crop box and the transformations required to set it up properly, an issue we have never previously looked at.

Question: I would like to set the crop box of a 3D view to correspond to a single room.

Answer: As the 3D view rotates the room, the original bounding box of the plan view will not be suitable to use for the 3D view crop box. Here is an idea to calculate the crop box. Retrieve all the corner point vertex coordinates of the room, and project them onto the plane perpendicular to the 3D view's view direction. This produces projected point coordinates. From these result point coordinates, determine the maximum and minimum X and Y values. From the max and min points, create the 3D view's crop box.

Here are the detailed steps to implement this idea:

• Retrieve all vertex coordinates of the room.
• Project these coordinates to the plane perpendicular to the 3D view's view direction. To do so, create a face perpendicular to the view direction. The projected results can be obtained from the Face.Project method taking an XYZ point argument. For more information, see the Revit API help file RevitAPI.chm for the usage and return value of this method.
• Go through the resulting coordinates and determine the maximum and minimum X and Y coordinate values.
• Use the four values to determine a bounding box:

  BoundingBoxXYZ bb = new BoundingBoxXYZ(); 
  bb.Min = NewXYZ( xMin, yMin, 0 );
  bb.Max = NewXYZ( xMax, yMax, 0 );
  

• Use the bounding box to set the 3D view crop box:

  View3d.CropBox = bb;
  

Actually, after some further investigation, I found a better way to determine the room extents. It is hard to create a solid and make one face of it perpendicular to the view direction.

You can also use the Transform class to calculate the crop box of the 3D view instead.

First, determine the transformation for translating coordinates in the 3D view to the world coordinate system WCS from the View3d.CropBox.Transform property. Then invert it to obtain the transformation to translate model WCS coordinates back to the 3D view coordinates.

Determine the room vertices from its ClosedShell property, and translate them to 3D view coordinates. Find the minimum and maximum X and Y coordinate values as described above and set the 3D view's crop box Max and Min properties using these.

You do need to activate and make the crop box visible to see the effect. You can do so using the Crop View and Show Crop Region buttons in the user interface:

This can also be achieved programmatically using:

  view3d.CropBoxActive = true;
  view3d.CropBoxVisible = true;

So far for Joe's idea. Many thanks to Joe for all the research into this!

I implemented a new Building Coder sample command CmdCropToRoom to test and demonstrate this. In order to show how the crop box can be set to various different regions in the model, it iterates over all the rooms in the model and sets the crop box of the current 3D view to the next room in the sequence on each call. We retrieve a list of all rooms in the model using doc.get_Elements:

List<RvtElement> rooms = new List<RvtElement>();
int n = doc.get_Elements( typeof( Room ), rooms );

To loop through the rooms in the model and step to the next room in the list on each invocation of the command, we use their index in the list of elements returned by this call. The last index used is stored in a static variable _i, and the method BumpRoomIndex is used to increment it by one on each call:

static int _i = -1;

static int BumpRoomIndex( int room_count )
{
  ++_i;
 
  if( _i >= room_count )
  {
    _i = 0;
  }
  return _i;
}

The next room to crop the view to is selected using

Room room = (0 < n) 
  ? rooms[BumpRoomIndex( n )] as Room 
  : null;

Here is the entire code of the CmdCropToRoom external command Execute method which crops the current 3D view to the next room extents:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
View3D view3d = doc.ActiveView as View3D;
 
if( null == view3d )
{
  message = "Please activate a 3D view"
    + " before running this command.";
 
  return CmdResult.Failed;
}
 
// get the 3d view crop box:
 
BoundingBoxXYZ bb = view3d.CropBox;
 
// get the transform from the current view 
// to the 3D model:
 
Transform transform = bb.Transform;
 
// get the transform from the 3D model 
// to the current view:
 
Transform transformInverse = transform.Inverse;
 
// get all rooms in the model:
 
List<RvtElement> rooms = new List<RvtElement>();
int n = doc.get_Elements( typeof( Room ), rooms );
 
Room room = (0 < n) 
  ? rooms[BumpRoomIndex( n )] as Room 
  : null;
 
if( null == room )
{
  message = "No room element found in project.";
  return CmdResult.Failed;
}
 
// collect all vertices of room closed shell 
// to determine its extents:
 
GeoElement e = room.ClosedShell;
XYZArray vertices = app.Create.NewXYZArray();
 
foreach( GeometryObject o in e.Objects )
{
  if( o is Solid )
  {
    // iterate over all the edges of all solids:
 
    Solid solid = o as Solid;
 
    foreach( Edge edge in solid.Edges )
    {
      foreach( XYZ p in edge.Tessellate() )
      {
        // collect all vertices, 
        // including duplicates:
 
        vertices.Append( p );
      }
    }
  }
}
 
XYZArray verticesIn3dView 
  = app.Create.NewXYZArray();
 
foreach( XYZ p in vertices )
{
  verticesIn3dView.Append( 
    transformInverse.OfPoint( p ) );
}
 
// ignore the Z coorindates and find the 
// min and max X and Y in the 3d view:
 
double xMin = 0, yMin = 0, xMax = 0, yMax = 0;
 
bool first = true;
foreach( XYZ p in verticesIn3dView )
{
  if( first )
  {
    xMin = p.X;
    yMin = p.Y;
    xMax = p.X;
    yMax = p.Y;
    first = false;
  }
  else
  {
    if( xMin > p.X )
      xMin = p.X;
    if( yMin > p.Y )
      yMin = p.Y;
    if( xMax < p.X )
      xMax = p.X;
    if( yMax < p.Y )
      yMax = p.Y;
  }
}
 
// grow the crop box by one twentieth of its 
// size to include the walls of the room:
 
double d = 0.05 * ( xMax - xMin );
xMin = xMin - d;
xMax = xMax + d;
 
d = 0.05 * ( yMax - yMin );
yMin = yMin - d;
yMax = yMax + d;
 
bb.Max = new XYZ( xMax, yMax, bb.Max.Z );
bb.Min = new XYZ( xMin, yMin, bb.Min.Z );
 
view3d.CropBox = bb;
 
// change the crop view setting manually or 
// programmatically to see the result:
 
view3d.CropBoxActive = true;
view3d.CropBoxVisible = true;
 
return CmdResult.Succeeded;

Here is a minimal model with two rooms to test this command:

Running the external command defined by CmdCropToRoom sets the 3D view crop box to the extents of the first room:

Running it another time increments the current room index and sets the 3D view crop box to its extents instead:

Here is version 1.1.0.56 of the complete Building Coder sample source code and Visual Studio solution including the new command.

There are a number of conceivable enhancements to this code. One of the most obvious would be to eliminate duplicate vertices before applying the inverse transformations and searching for the minimum and maximum coordinate values. We did implement some useful functionality for doing that with the XyzEqualityComparer class and GetVertices method in the nested instances geometry retrieval. It might also be possible to use generic collections such as List<XYZ> instead of XYZArray for the original and transformed vertices, and generic .NET functionality to apply the transformation and determine the max and min coordinate values. We left out such enhancements in this case for the sake of clarity, but if you have any suggestions to make, please feel free to do so.

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.

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.