The Building Coder

Slab Boundary

Developers have frequently asked how to determine the boundary polygons of a horizontal slab, e.g. the loops formed by the bottom edges of all the vertical or 'side' faces in this floor:

In this case, there is one outer and three inner loops, one of which is circular.

There are several different possible approaches to obtain this information, and you will need to decide which is simplest or most effective or optimally suited to provide the data you require in each individual case. Here is a suggestion for a very straightforward algorithm: determine the slab solid, iterate over its faces, ignore all non-horizontal faces, and determine which of the horizontal ones has the lowest Z coordinate. Query the lowest face for its edge loops, and collect all its vertices into a structure for handling the polygon data.

I have implemented an external command CmdSlabBoundary realising this algorithm. For the polygon data, I use a list of lists of points. Each list of points represents one closed polygonal loop. This means that non-linear polygon edges will have to be approximated by straight segments. If you need to handle other curve types such as circular arcs or ellipses exactly, you would have to enhance this definition. It currently only handles planar faces on horizontal slabs. It uses the Edge Tesselate method, which returns a polyline approximation to the edge, to extract the points to be added to the boundary polygon.

Here is the code for the mainline of the command. It implements some useful code to determine which floor elements to process. It first checks whether anything at all has been selected. If so, it extracts the floor elements from the selection and returns with an error message if none are found. If nothing has been preselected by the user before starting the command, it selects all floor elements from the model, and again returns with an error message if none are found. Then, for each floor, the geometry is extracted and the solid is passed into the GetBoundary() method for analysis:

public CmdResult Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  List<RvtElement> floors = new List<RvtElement>();
  Selection sel = doc.Selection;
  if( 0 < sel.Elements.Size )
  {
    foreach( RvtElement e in sel.Elements )
    {
      if( e is Floor )
      {
        floors.Add( e );
      }
    }
    if( 0 == floors.Count )
    {
      message = "Please select some floor elements.";
      return CmdResult.Failed;
    }
  }
  else
  {
    doc.get_Elements( typeof( Floor ), floors );
    if( 0 == floors.Count )
    {
      message = "No floor elements found.";
      return CmdResult.Failed;
    }
  }
 
  List<List<XYZ>> polygons = new List<List<XYZ>>();
  Options opt = app.Create.NewGeometryOptions();
 
  foreach( Floor floor in floors )
  {
    GeoElement geo = floor.get_Geometry( opt );
    GeometryObjectArray objects = geo.Objects;
    foreach( GeometryObject obj in objects )
    {
      Solid solid = obj as Solid;
      if( solid != null )
      {
        GetBoundary( polygons, solid );
      }
    }
  }
 
  int n = polygons.Count;
 
  Debug.WriteLine( string.Format(
    "{0} boundary loop{1} found.",
    n, Util.PluralSuffix( n ) ) );
 
  Creator creator = new Creator( app );
  creator.DrawPolygons( polygons );
 
  return CmdResult.Succeeded;
}

Here is the implementation of GetBoundary(); I added a constant value to offset the boundary polygons downward a bit, away from the slab edge, so that they are more clearly visible:

const double _offset = 0.1;
 
bool GetBoundary(
  List<List<XYZ>> polygons,
  Solid solid )
{
  PlanarFace lowest = null;
  FaceArray faces = solid.Faces;
  foreach( Face f in faces )
  {
    PlanarFace pf = f as PlanarFace;
    if( null != pf && IsHorizontal( pf ) )
    {
      if( ( null == lowest )
        || ( pf.Origin.Z < lowest.Origin.Z ) )
      {
        lowest = pf;
      }
    }
  }
  if( null != lowest )
  {
    XYZ p, q = XYZ.Zero;
    bool first;
    int i, n;
    EdgeArrayArray loops = lowest.EdgeLoops;
    foreach( EdgeArray loop in loops )
    {
      List<XYZ> vertices = new List<XYZ>();
      first = true;
      foreach( Edge e in loop )
      {
        XYZArray points = e.Tessellate();
        p = points.get_Item( 0 );
        if( !first )
        {
          Debug.Assert( p.AlmostEqual( q ),
            "expected subsequent start point"
            + " to equal previous end point" );
        }
        n = points.Size;
        q = points.get_Item( n - 1 );
        for( i = 0; i < n - 1; ++i )
        {
          XYZ v = points.get_Item( i );
          v.Z -= _offset;
          vertices.Add( v );
        }
      }
      q.Z -= _offset;
      Debug.Assert( q.AlmostEqual( vertices[0] ),
        "expected last end point to equal"
        + " first start point" );
      polygons.Add( vertices );
    }
  }
  return null != lowest;
}

Here is the result displaying the model lines added after processing, with all lines offset downwards from the slab edge by 0.1 feet, and one of the edges approximating the bottom of the circular opening highlighted:

Finally, here are the model lines isolated to distinguish them better from the slab:

I hope this provides a good geometrical analysis example and a starting point for further exploration. Obviously, I am interested in any improvements you may have or bugs that you find.

I am adding a new version 1.0.0.9 of the complete Visual Studio solution here, including the new CmdSlabBoundary class as well as all other commands discussed so far.

Element Bounding Box

Here is a topic suggested by Michael Raps of the Institut 4D-Technologies and DataSpaces at the Fachhochschule Nordwestschweiz regarding the Element BoundingBox property.

This property is documented in the Revit API help file, which says that it retrieves a box that circumscribes all geometry of the element. It takes a parameter of type View, from the Revit Elements namespace. According to the help file, it returns a bounding box for the model geometry if the view parameter is null, and otherwise the view specific geometry, for instance in a section or cut view. If the view bounding box is not known, it will return the model box; if that is not known, it will return null.

Like several other Revit API properties, this one is not accessible in C# directly as BoundingBox. If you try to call that property on an element instance, Visual Studio will return a compile time error: Property, indexer, or event 'BoundingBox' is not supported by the language; try directly calling accessor method 'get_BoundingBox( View )'. Accordingly, Intellisense will not display any such property, only the method listed in the error message instead.

The BoundingBoxXYZ class is also used in other contexts as well as by the Element BoundingBox property, such as for defining a section view or crop box in a 3D view.

The main properties of the bounding box class are Min, Max and Transform, to retrieve or modify its upper and lower bounds and position it in space. It has other methods as well, which are not relevant to the usage by the Element BoundingBox property.

The bounding box returned by the Element BoundingBox property is parallel to the cardinal coordinate axes in the project space, so it has no relationship to the element coordinate system and is not necessarily the smallest possible circumscribing box, which would generally not be aligned with the cardinal axes. Therefore, the Transform property of a bounding box returned in this context will always be the identity transformation.

Some more information on the Geometry BoundingBoxXYZ class is provided in section 17.3.5 of the Revit 2009 API Developer Guide.

Here is a simple command that explores the bounding box properties of a selected element:

public CmdResult Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  Element e = Util.SelectSingleElement(
    doc, "an element" );
 
  if( null == e )
  {
    message = "No element selected";
    return CmdResult.Failed;
  }
 
  BoundingBoxXYZ b = e.get_BoundingBox( null );
 
  Debug.Assert( b.Transform.IsIdentity,
    "expected identity Element bounding box transform" );
 
  Debug.WriteLine( string.Format(
    "Element bounding box of {0}"
    + " extends from {1} to {2}.",
    Util.ElementDescription( e ),
    Util.PointString( b.Min ),
    Util.PointString( b.Max ) ) );
 
  return CmdResult.Succeeded;
}

We examine the bounding boxes of two 10 metre long and 20 cm thick walls, i.e. a bit over 32 feet long and 0.65 thick, one parallel to the X axis, the other at 45 degrees to it. Both of them are connected to level 1 at the bottom and level 2 at the top, 4 metres high, a bit more than 13 feet:

Element bounding box of Walls <127876 Generic - 200mm> 
  extends from (11.77,35.66,0) to (45.38,36.32,26.25).
Element bounding box of Walls <127933 Generic - 200mm> 
  extends from (44.35,35.76,0) to (68.01,59.42,26.25).

As you can see, the bounding boxes are both aligned with the principal axes, so the one for the wall parallel to the X axis is optimal, i.e. minimal, whereas the one at a 45 degree angle is not.

Inserting a window into the horizontal wall and examining that returns:

Element bounding box of Windows M_Fixed <127959 0406 x 0610mm> 
  extends from (27.51,35.66,3) to (28.84,37.49,5).

Converting the values returned from feet to metric returns more or less the expected window dimensions:

  inch = 2.54 cm
  foot = 12 * inch = 30.48 cm
  (28.84 - 27.51) * foot = 40.5384 cm
  2 * foot = 60.96 cm

I hope this helps clarify this simple Element property somewhat.

I am adding a new version 1.0.0.8 of the complete Visual Studio solution here, including the new CmdBoundingBox class as well as all other commands discussed so far.

Obfuscation

In response to the last post, Rod Howarth brought up the related topic of source code obfuscation for a .NET assembly. He says:

Reflector is certainly a useful tool, and it’s good to delve into both your own code and other namespaces. It can greatly assist with understanding code and also disaster recovery, in the case of lost source files.

A related topic is obfuscation, as the first thing that one thinks about when you realize that your DLL file is easily convertible back to source code is the possible loss of intellectual property. Codecall and the Microsoft .NET Support Team have quick tutorials about dotfuscator, which comes with Visual Studio. There are also a number of 3rd party tools. Xenocode Postbuild and CodeVeil are a couple of names I’ve heard used.

Converting between VB and C#, and .NET Decompilation

Here is post to follow up on the comment on converting between C# and VB code by Rod Howarth on the post on Application Events in VB.

First of all, converting code between C# and VB is possible and can be done automatically. C# and VB.NET both produce the identical intermediate language IL code, which is what is actually stored in the .NET assembly and evaluated by the .NET framework. The IL code contains all information required to regenerate the source code. So, on one hand, you can translate between C# and VB. Furthermore, you can even recreate source code in any language of your choice by decompiling the IL code in the assembly.

To translate between C# and VB, just google for "c# vb translator". Rod mentioned a couple of such translators; he says:

Also useful for anyone who is a VB coder and wants to convert samples are the many VB to C# code converters available. Using a Google query such as this one will turn up tools such as http://www.developerfusion.com/tools/convert/csharp-to-vb and http://www.carlosag.net/Tools/CodeTranslator. They may not do whole projects but they can help you decipher the samples!

To analyse or decompile any .NET assembly, even without access to the source code, a tool that I use is Reflector by Lutz Roeder.

It includes reverse engineering functionality, for instance a decompilation and source code generation feature, so it can read your compiled DLL and decompile the IL intermediate language it contains into various languages including C#, VB, managed C++, and others. It can obviously also be used to list all namespaces and classes defined in an assembly, and their methods and properties.

Here is an example of decompiling a Revit external command assembly I built using C# and requesting VB code for it:

See the VB code? I wrote this application in C#! My version of Reflector will also decompile into Delphi, Chrome and managed C++, besides C# and VB.

Although ... please note that even Reflector is not always 100% correct ... if you look carefully at the screen snapshot, note that it seems to have come up with something strange; in the line following

If (Not Nothing Is PlanarFace) Then

it says

Dim <>8__locals2 As <>c__DisplayClass1

That will probably not compile correctly. Thanks to Adam Nagy, a DevTech colleague of mine, for noticing this error.

I find this an invaluable tool, and often use it to explore my own .NET assemblies, just to ensure that they really do contain what I am expecting them to.

Azimuth

Several developers have asked how to determine the azimuth of an element, i.e. the angle between the element and true north. This calculation is obviously strongly affected by the project location.

Determining the angle of an element is pretty simple. All Revit elements have a Location property. For some, the location is a point, while others can be line or curve based, in which case their location is an instance of the LocationCurve class. One of the properties of the LocationCurve is Curve, which returns the actual geometry curve, which may be one of the derived classes Arc, Line, Ellipse or NurbSpline. In addition to providing access to the underlying geometry curve, the location curve class also provides methods to move and rotate the element whose location it defines, and to determine or modify the order of the neighbouring elements joining to the end of the element's location curve.

In order to determine the angle of an element, you can convert the two endpoints of its location curve to a vector and then measure the angle of that vector relative to some other vector, for instance the X axis or the north direction.

Revit stores true north in the ProjectPosition object stored in the ProjectLocation, accessible through the ProjectLocations property on the document object. You can query the ProjectPosition.Angle property, which returns the angle difference between the project north and true north measured in radians. It can have a value from -π to +π.

To determine the element azimuth, you can determine the element angle and the angle between project north and true north, and then simply add the two.

Some notes on the Revit geometry angle methods: The Angle() method of the XYZ class treats its XYZ instances as vectors, not points. This is what the Revit API help has to say about this:

The XYZ.Angle() method returns the angle between this vector and the specified vector.
Return Value: The real number between 0 and π equal to the angle between the two vectors.
Remarks: The angle between the two vectors is measured in the plane spanned by them.

If you are interested in angles around the full circle, i.e. in the interval [0, 2π], you should use AngleTo() instead of Angle(), which returns a value in the interval [0, π].

Here is a code example measuring various kinds of element angles and printing the project north deviation:

class CmdAzimuth : IExternalCommand
{
  Element SelectSingleElement( Document doc )
  {
    Selection sel = doc.Selection;
    Element e = null;
    sel.Elements.Clear();
    sel.StatusbarTip = "Please select a line";
    if( sel.PickOne() )
    {
      ElementSetIterator elemSetItr
        = sel.Elements.ForwardIterator();
      elemSetItr.MoveNext();
      e = elemSetItr.Current as Element;
    }
    return e;
  }
 
  public CmdResult Execute(
    ExternalCommandData commandData,
    ref String message,
    ElementSet elements )
  {
    Application app = commandData.Application;
    Document doc = app.ActiveDocument;
    Element e = SelectSingleElement( doc );
 
    if( null == e )
    {
      message = "No element selected";
      return CmdResult.Failed;
    }
 
    LocationCurve curve
      = e.Location as LocationCurve;
 
    if( null == curve )
    {
      message = "No curve available";
      return CmdResult.Failed;
    }
 
    XYZ p = curve.Curve.get_EndPoint( 0 );
    XYZ q = curve.Curve.get_EndPoint( 1 );
 
    Debug.WriteLine( "Start point "
      + Util.PointString( p ) );
 
    Debug.WriteLine( "End point "
      + Util.PointString( q ) );
 
    double a = p.Angle( q );
    Debug.WriteLine(
      "Angle between start and end points = "
      + Util.AngleString( a ) );
 
    XYZ v = q - p;
    a = XYZ.BasisX.Angle( v );
    Debug.WriteLine(
      "Angle between points measured from X axis = "
      + Util.AngleString( a ) );
 
    XYZ z = XYZ.BasisZ;
    a = XYZ.BasisX.AngleAround( v, z );
    Debug.WriteLine(
      "Angle around measured from X axis = "
      + Util.AngleString( a ) );
 
    foreach( ProjectLocation location
      in doc.ProjectLocations )
    {
      ProjectPosition projectPosition
        = location.get_ProjectPosition( XYZ.Zero );
      double pna = projectPosition.Angle;
      Debug.WriteLine(
        "Angle between project north and true north "
        + Util.AngleString( pna ) );
    }
    return CmdResult.Succeeded;
  }
}

Running this command in a project and selecting a model line with an angle of 35 degrees to the X axis generates the following result in the Visual Studio debug output window:

Start point (-43.84,31.27,0)
End point (-28.79,41.81,0)
Angle between start and end points = 19.95 degrees
Angle between points measured from X axis = 35 degrees
Angle around measured from X axis = 35 degrees
Angle between project north and true north 0 degrees

You might also have a look at the Revit SDK SharedCoordinateSystem sample to see another example of using the ProjectPosition object.

I am adding the complete Visual Studio solution here. This version 1.0.0.7 includes all commands discussed so far: CmdListWalls, CmdRelationshipInverter, CmdWallDimensions, CmdFilterPerformance, CmdGetMaterials and the new CmdAzimuth.

Family Instance Materials

In the previous post, we read out materials from walls and other building elements by querying them for their geometry, picking out all the solids, and iterating over their faces. However, for family instances such as doors and windows, we noticed that no solid is present in the top level objects contained by the geometry element.

Family instances make use of a geometry instance to define their geometry. The geometry instance provides the facility to reuse symbol geometry in multiple locations for different family instances of the same symbol. Its most important properties to support this are:

• Symbol: The symbol element that this object is referring to.
• SymbolGeometry: The geometric representation of the symbol.
• Transform: The affine transformation from the local coordinate space of the symbol into the coordinate space of the instance.

In our current task of listing the materials used by the building elements, we do not need to examine the transformations applied to the instance geometry. If we were interested in face coordinates, we would have to keep track of that information.

In our case, to determine materials used in the door and window family instances, all we have to do is add one level of recursion to the existing GetMaterials() implementation. We need to check for geometry instance objects as well as solids. In case of an instance, we can access the symbol geometry and make a recursive call to GetMaterials() to pick out the materials from that as follows:

public List<string> GetMaterials( GeoElement geo )
{
  List<string> materials = new List<string>();
  foreach( GeometryObject o in geo.Objects )
  {
    if( o is Solid )
    {
      Solid solid = o as Solid;
      foreach( Face face in solid.Faces )
      {
        string s = face.MaterialElement.Name;
        materials.Add( s );
      }
    }
    else if( o is GeoInstance )
    {
      GeoInstance i = o as GeoInstance;
      materials.AddRange( GetMaterials(
        i.SymbolGeometry ) );
    }
  }
  return materials;
}

Note that we added an additional alias to our namespace references to disambiguate the Revit element and geometry instance classes:

using GeoInstance = Autodesk.Revit.Geometry.Instance;

With the additional code in place, we obtain the same materials as before for the walls, floor and roof, and additionally a long list of new materials for the numerous family instance faces:

Walls <127248 Generic - 200mm> has 17 materials:
  0 Default Wall
  . . .
  16 Default Wall
Walls <127249 Generic - 200mm> has 6 materials:
  0 Default Wall
  . . .
  5 Default Wall
Walls <127250 Generic - 200mm> has 6 materials:
  0 Default Wall
  . . .
  5 Default Wall
Walls <127251 Generic - 200mm> has 6 materials:
  0 Default Wall
  . . .
  5 Default Wall
Doors M_Single-Flush <127252 0915 x 2134mm> has 26 materials:
  0 Door - Frame
  1 Door - Frame
  2 Door - Frame
  3 Door - Frame
  . . .
  19 Door - Frame
  20 Door - Panel
  21 Door - Panel
  . . .
  25 Door - Panel
Windows M_Fixed <127255 0406 x 0610mm> has 36 materials:
  0 Glass
  1 Glass
  . . .
  5 Glass
  6 Sash
  7 Sash
  . . .
  35 Sash
Windows M_Fixed <127258 0406 x 0610mm> has 36 materials:
  0 Glass
  1 Glass
  . . .
  5 Glass
  6 Sash
  7 Sash
  . . .
  35 Sash
Floors <127266 Generic Floor - 400mm> has 6 materials:
  0 Default Roof
  . . .
  5 Default Roof
Roofs <127269 Generic Roof - 300mm> has 12 materials:
  0 Default Roof
  . . .
  11 Default Roof

As you can see, the material assignments on the family instance solid faces may allow us to differentiate between the different element components, such as the door frame and panel, and the window glass and sash. This is however dependant on the family definition, so there is no guarantee that this approach will work for all families.

An interesting next step would be to analyse how to make use of the transformations defined by the nested geometry instances to calculate the real world coordinates. How to do this is actually demonstrated by the various geometry viewers that we already discussed.

I am adding the complete Visual Studio solution here. This version 1.0.0.6 includes all commands we discussed so far: CmdListWalls, CmdRelationshipInverter, CmdWallDimensions, CmdFilterPerformance and the updated version of CmdGetMaterials.

Element Materials

I recently heard several queries on how to access the surface material of a wall or other building element. There are several different ways to access materials defined on building elements. One method is discussed in the section 16.3 Element Material in the Revit 2009 API Developer Guide. Another method goes through the geometry and retrieves the material associated with each face. We will discuss the latter approach in this and the next post.

Retrieving the material associated with element geometry is actually very simple, similar to and simpler than the geometrical traversal that we looked at in the post on Wall Dimensions. The geometry displayed in Revit generally has a solid associated with it, each solid has a set of faces, and each face has a material, which can be queried using its MaterialElement property. Therefore, we can simply query the building element for its geometry, traverse that, pick out all solids, ask each one for its faces, and list their materials. Here is the code to do so:

using System;
using System.Collections.Generic;
using System.Diagnostics;
using Autodesk.Revit;
using Autodesk.Revit.Elements;
using Autodesk.Revit.Geometry;
using CmdResult = Autodesk.Revit.IExternalCommand.Result;
using RvtElement = Autodesk.Revit.Element;
using GeoElement = Autodesk.Revit.Geometry.Element;
 
namespace BuildingCoder
{
  class CmdGetMaterials : IExternalCommand
  {
    public List<string> GetMaterials( GeoElement geo )
    {
      List<string> materials = new List<string>();
      foreach( GeometryObject o in geo.Objects )
      {
        if( o is Solid )
        {
          Solid solid = o as Solid;
          foreach( Face face in solid.Faces )
          {
            string s = face.MaterialElement.Name;
            materials.Add( s );
          }
        }
      }
      return materials;
    }
 
    public CmdResult Execute(
      ExternalCommandData commandData,
      ref string message,
      ElementSet elements )
    {
      Application app = commandData.Application;
      Document doc = app.ActiveDocument;
      Selection sel = doc.Selection;
      Options opt = app.Create.NewGeometryOptions();
      string msg = string.Empty;
      int i, n;
 
      foreach( RvtElement e in sel.Elements )
      {
        GeoElement geo = e.get_Geometry( opt );
        List<string> materials = GetMaterials( geo );
 
        msg += "\n" + Util.ElementDescription( e );
 
        n = materials.Count;
        if( 0 == n )
        {
          msg += " has no materials.";
        }
        else
        {
          i = 0;
          msg += string.Format(
            " has {0} material{1}:",
            n, Util.PluralSuffix( n ) );
 
          foreach( string s in materials )
          {
            msg += string.Format(
              "\n  {0} {1}", i++, s );
          }
        }
      }
      if( 0 == msg.Length )
      {
        msg = "Please select some elements.";
      }
      Util.InfoMsg( msg );
      return CmdResult.Succeeded;
    }
  }
}

Here is the little house sample, consisting of four walls, a floor, a roof, a door and two windows, which we can run this code on:

Here is the result of selecting all elements of the little house and running the command:

Walls <127248 Generic - 200mm> has 17 materials:
  0 Default Wall
  1 Default Wall
  2 Default Wall
  3 Default Wall
  . . .
  16 Default Wall
Walls <127249 Generic - 200mm> has 6 materials:
  0 Default Wall
  1 Default Wall
  . . .
  5 Default Wall
Walls <127250 Generic - 200mm> has 6 materials:
  0 Default Wall
  1 Default Wall
  . . .
  5 Default Wall
Walls <127251 Generic - 200mm> has 6 materials:
  0 Default Wall
  . . .
  5 Default Wall
Doors M_Single-Flush <127252 0915 x 2134mm> has no materials.
Windows M_Fixed <127255 0406 x 0610mm> has no materials.
Windows M_Fixed <127258 0406 x 0610mm> has no materials.
Floors <127266 Generic Floor - 400mm> has 6 materials:
  0 Default Roof
  1 Default Roof
  . . .
  5 Default Roof
Roofs <127269 Generic Roof - 300mm> has 12 materials:
  0 Default Roof
  1 Default Roof
  . . .
  11 Default Roof

Notice that the sample in its current state does not report any materials for the door or windows. This is because these elements are family instances, and their geometry is nested in a geometry instance, which the current code does not traverse into. In a future instalment, we will rectify that to list the materials nested in family instances as well.

I am adding the complete Visual Studio solution here. This version 1.0.0.5 includes all commands we discussed so far: CmdListWalls, CmdRelationshipInverter, CmdWallDimensions, CmdFilterPerformance and the new CmdGetMaterials.

Application Events in VB

I do not work much in VB, but somebody recently asked how to subscribe to the Revit application events in that language. There is no VB sample for this in the Revit SDK samples, so I created the following little solution to demonstrate it.

The steps to create it are exactly the same as for a C# project, and were actually described in detail for both C# and VB in the post on Debugging a Revit Add-In, but here is the really short version:

• Create a new class library project
• Reference RevitAPI.dll
• Set its 'Copy Local' flag to false
• Derive your class from IExternalApplication
• Implement the member methods

I have copied the full Visual Studio solution AppEventsVb here. It is very straight forward to create from scratch, actually, and using Intellisense as much as possible really helps. For instance, the moment I typed 'Implements IExternalApplication.OnShutdown', the skeleton code for two methods is automatically added by Visual Studio.

RVT File Version

And now for something completely different.

The Revit API does not provide any method for determining the version of an RVT file on disk. And even if it did, it would often be useful to be able to determine the file version from outside of Revit, i.e. without having access to the Revit API. Happily, this is easily possible and also gives us a chance to look at a completely different programming environment, for a welcome change.

To see how easy it is to discover this information in the binary RVT file, you can simply try opening an RVT file in the Visual Studio editor. It will open it in binary mode, so it will be displayed in hexadecimal. Scrolling through the gibberish, you will occasionally see some intelligible strings. Since they are in Unicode, there will be intervening null bytes between the individual ASCII characters. Sooner or later, one of these will say 'Build:', followed by the build number.

Actually, the RVT file is an OLE document. It contains various separate sections, and these can be viewed using the Windows NT Structured Storage Docfile Viewer dfview.exe. It is an executable from Windows 3.50.1, and was also shipped with Visual Studio 6.0 (^). By the way, looking at a RVT file in dfview.exe also shows that the bitmap is buried somewhere in there, in a branch named RevitPreview4.0 ... but that is a different topic. Here is an example of dfview displaying a Revit document named wall.rvt:

Enough said. Almost. Another note I would like to make is that you as a professional programmer certainly must be aware of the fact that for little free-standing programming tasks like extracting this Unicode build string from a binary file, and actually for large programming tasks as well, scripting languages are vastly more efficient than compiled ones. For a discussion of this, you can refer to this paper by John Ousterhout, the father of the Tcl/Tk scripting and GUI language, which discusses the impressive effort ratio ranging between 3 and 60 comparing both small and large programming tasks implemented in a compiled language such as C, C++ or Java versus scripted versions in Tcl and Perl. Regardless of whether the compiled or scripted version was written first, the scripted version comes out on top. On the other hand, with very strong support for Intellisense and on-the-fly recompilation during the debugging session for both C++ and .NET, the Visual Studio development environment is improving as well.

A handy scripting language that I use a lot nowadays is Python. I did use Perl for a year or two, but since that does has tendency towards being a write-only language, I have gradually tended towards Python lately. Here is the source code for a Python script that reads the entire RVT file into memory, searches for the Unicode build string, and prints the result:

"""
rvtver.py - read Revit version from *.rvt file

Copyright (C) 2008 by Jeremy Tammik, Autodesk Inc.

2008-09-02 initial version
2008-10-01 unicode handling added by ralf huvendiek
"""

import os, sys

if 1 == len(sys.argv):
 print 'usage: a.py rvtfile'
 sys.exit()

filename = sys.argv[1]

if not os.path.exists( filename ):
 print "File '%s' does not exist." % filename
 sys.exit()

f = open( filename, 'rb' )
data = f.read()
f.close()

s = 'Build'.encode( 'UTF-16-LE' )
i = data.find( s )

if i > 0:
 build_string = data[ i: i+40 ]
 build_string = build_string.decode( 'UTF-16-LE' )
 print "Build string found in '%s' at offset %s: %s" % (filename, i, build_string)
else:
 print 'Build string not found.'

Many thanks to Ralf Huvendiek for checking the code and adding the Unicode conversion calls. As Ralf pointed out and many of you are certainly aware, this little script can quickly become a pretty monstrous memory hog, since f.read() will attempt to read in the entire RVT file into memory in one go. This just goes to underline the fact that this is not production code, just a proof of concept. Production code or even a useful generic little utility would read the file one chunk at a time and terminate once the search string is found. In my tests so far, the string occurred pretty early on, so it should terminate pretty quickly.

Picking a Point

I am regularly asked by developers how to pick a point in Revit. This is currently not possible. The wish has been registered, but there are no plans to provide this functionality in the short term. The only interactive selection methods available in the API are the PickOne() and WindowSelect() methods on the Selection class in the Autodesk.Revit namespace, which prompt the user to select one or several building elements.

If you need the user to specify a point somewhere in the model, you can look at some of the SDK samples for an idea how the lack of a point selection mechanism on the Revit graphics screen can be circumvented.

For instance, the CurtainWallGrid sample displays a form with two tabs in it. The first tab is designed for the user to create a new curtain wall. To do so, she needs to specify the wall start and end points for the wall baseline. This is done graphically on a canvas representing the XY plane in the model.

Once the curtain wall has been created, the next tab can be used to graphically define the grid lines on it. This time, a canvas displaying the wall face is shown, and the user can interactively add, delete and move grid lines around.

Several other SDK samples also display their own little graphics windows allowing user interaction to specify points in space or on selected objects. They include NewOpenings, NewPathReinforcement, and ShaftHolePuncher, to name a few.

I hope this provides some ideas and a starting point for you in case you happen to run into this requirement.

By the way, if you make use of the PickOne() and WindowSelect() methods, note that you can also use the StatusbarTip property to define the message displayed in the Revit status bar to prompt the user what selection to make. If you need to display more information, you can also show a temporary modeless little form of your own while prompting for the selection.

SDK Update Posted

The Revit 2009 web update 2 has been posted to the Autodesk product site for the English versions of Revit Architecture, MEP and Structure. Unlike previous versions, this update makes use of patching technology and does not require a complete reinstallation. For this reason, the SDK is not included in the update, like it used to be in previous versions. Therefore, the Revit 2009 SDK web update 2 has been posted separately. It is available under the link Revit 2009 SDK (Update 2) (zip - 61330Kb) in the Revit Developer Center as well as on ADN. Among other things, the updated version includes the RoofsRooms SDK sample, the Revit 2009 API Developer Guide and the 'Guide to placing Family Instances with the API.doc' mentioned in The Revit SDK Contents.

Filter Performance Conclusion

Continuing the topic of the Revit API filter performance, Guy responds to Ralf:

Ralf raises some good points.

A good point on the order in filters, I did not think about that and I did think the speed improvement was larger than normal. I've found in past testing using the TypeFilter in most cases 2-10% slower than using some form of .NET filtering for real world projects and where other filters are not appropriate.

I agree that an anonymous method is not as elegant; I haven't used this method in any production code. It just gave you a list as per your original code. Almost without exception, all my commands use the ElementIterator getElements() rather than populating a list. And for that reason the point I should have made in the previous post was that IMO I still think the TypeFilter is redundant. This is how I would have processed the elements in the command:

  Filter f1 = cf.NewCategoryFilter(
    BuiltInCategory.OST_Doors );

  Filter f2 = cf.NewCategoryFilter(
    BuiltInCategory.OST_Windows );

  Filter f3 = cf.NewLogicOrFilter( f1, f2 );

  ElementIterator itor = doc.get_Elements( f3 );
  int n = 0;
  while( itor.MoveNext() )
  {
    if( itor.Current is FamilyInstance )
    {
      n++;
      FamilyInstance elem = itor.Current
        as FamilyInstance;
    }
  }

Against the 100 MB project this is still 1-3% faster than including the type filter, even including the casting to a FamilyInstance.

The other point Ralf raises is that x >> y where x is the total element number and y is the number of elements of interest, e.g. of the desired category. I would go a step further and say for most commands x >> y >> z, where z is the number of particular instances of a family you are interested in processing. For that reason a vast majority of production commands I've written use parameter filtering, yet I have none with type filtering.

I've also found in testing that type filter performance is very dependent on whether a project has been recently purged of unused objects. As users will know, purging on a regular basis helps project performance. The difference in performance between a purged versus a non purged project for API commands can be very dramatic, as the total object count often drops significantly.

As you can tell, I'm not a big fan of the type filter but every project is different ;-)

For completeness sake, here is how I would use the ElementIterator in the original code:

private Dictionary<ElementId, List<ElementId>>
  getElementIds( ElementIterator itor)
{
  Dictionary<ElementId, List<ElementId>> dict
    = new Dictionary<ElementId, List<ElementId>>();

  string fmt = "{0} is hosted by {1}";

  while( itor.MoveNext() )
  {
    object elem = itor.Current;
    if( elem is FamilyInstance )
    {
      FamilyInstance fi = elem as FamilyInstance;
      ElementId id = fi.Id;
 
      ElementId idHost = fi.Host.Id;
 
      Debug.WriteLine( string.Format( fmt,
        ElementDescription( fi ),
        ElementDescription( idHost ) ) );

      if( !dict.ContainsKey( idHost ) )
      {
        dict.Add( idHost, new List<ElementId>() );
      }
      dict[idHost].Add( id );
    }
  }
  return dict;
}

More Filter Performance

This post is a response to Guy Robinson's contribution on Filter Performance, and is also by a reader, Ralf Huvendiek. Ralf only recently started working on the Revit API, but brings such a wealth of prior programming experience and enthusiasm that I am very grateful for his invaluable input. He says:

Guy raises an interesting question regarding the performance of the Revit filters. I think he comes to the right conclusion, but not the best solution or explanation.

First we need to agree about a few things. Let us assume the following:

1. Our drawing contains x elements.
2. x is very high.
3. Our drawing contains d doors and w windows.
4. d+w is a lot smaller than x.
5. The Revit TypeFilter has to use some kind of RTTI and is thus much slower than a plain CategoryFilter.

Now let us return to the original filter, which was

  (TypeFilter && (CategoryFilter || CategoryFilter))

To evaluate that filter, Revit has to invoke the TypeFilter x times, because it is the first filter in our Boolean expression.

If we look at the points 'b' and 'e' above, we see that this is not very desirable. With a look at our Boolean expression, and the fact that '&&' is commutative, we can reorder the filter like this:

   ((CategoryFilter || CategoryFilter) && TypeFilter)

Now our cheap CategoryFilter will be called ~x times and the expensive TypeFilter will only be called (w+d) times.

With this knowledge, we can reorder Jeremy's original code from:

  Filter f5 = cf.NewLogicAndFilter( f1, f4 );

To:

  Filter f5 = cf.NewLogicAndFilter( f4, f1 );

The CmdRelationshipInverter modified as described is just as fast as the Guy's solution. This is not surprising, because his code does the same thing in a different way: prefilter everything with f4, and then use the expensive RTTI to filter out the rest afterwards. But I think Jeremy's solution from with a modified filter f5 is much cleaner than filtering using an anonymous method.

What can we conclude from this:

1. If we're writing a performance critical filter, we should be aware how to organize it best: put the expensive filters as far to the right as possible.
2. We can't blame the Revit API for being slow here. It's just the filter that is not optimal.

Ralf measured the times running the various variants of the command that we discussed so far on one of the standard Revit sample files, using the following setup parameters:

• Revit version: Revit Architecture Build 20080508_1900 (German)
• Project: m_Conference.rvt from Revit Samples
• Number of elements in model: 14153
• Number of windows and doors: 50
• Machine used for testing: Windows XP SP3 German / CPU: Core 2 Duo E6850 / 2GB RAM
• Compiler: Visual Studio 2005 Team Edition (SP1)

Here are the resulting times:

Test run	Original filter	Guy's code	Optimised filter
1	170	58	58
2	170	57	58
3	171	57	58
4	191	57	58
5	171	57	58
6	171	57	58
7	170	57	58
8	170	57	58
9	197	57	58
10	172	57	58

AU 2008

I am very much looking forward Autodesk University 2008 in December in Las Vegas, where I will be presenting classes on some Revit API topics:

• DE101-3   The Revit SDK Sample Smörgåsbord
  Tue. 12/2 8:15 am - 9:45 am
• DE205-3   Enhancing Your Revit Add-In
  Wed. 12/3 10:15 am - 11:45 am
• DE301-2   The Ins and Outs of Revit MEP Programming
  Thu. 12/4 8:15 am - 9:45 am

I will also be part of the panel for

• DE315-1   AEC API Talk
  Thu. 12/4 3:15 pm - 4:45 pm

The full class schedule for AU 2008 has been published on Joseph Wurcher's BLAUG.

My presentations are part of this year's Developer Track sessions, presented by colleagues from the Autodesk DevTech and various Engineering teams. Kean Walmsley has presented the full list of Developer Track sessions on his blog Through the Interface.

I very much hope I will get a chance to meet some of you in person at AU!

Filter Performance

This post is entirely thanks to Guy Robinson, who has always been the quickest to test and comment on performance issues in the Revit API, in response to the previous post. He says:

Like you, I initially thought the TypeFilter was a more elegant filter for FamilyInstances etc., but having done a lot of testing I now have my suspicions regarding how filters work internally and why it's not necessarily a good filter option for certain element types.

In the relationship code for this situation, it is significantly faster to just use the category filter as demonstrated in the command below. On a 100 MB project, I compared the times required to retrieve 571 elements using the type filter as shown in the previous post versus using an anonymous method to filter away objects of the wrong type after receiving them from Revit. These are the execution times for running the two commands a repeated number of times:

using TypeFilter:
Time to get 571 elements 37226
Time to get 571 elements  6042
Time to get 571 elements  6024
Time to get 571 elements  6172

using anonymous method:
Time to get 571 elements 33769
Time to get 571 elements  2052
Time to get 571 elements  2050
Time to get 571 elements  2048
Time to get 571 elements  2034
Time to get 571 elements  2037

As you can see, using the anonymous method is three times as fast. So while filters are fantastic, they're not always the best solution ;-)

So much for the comment from Guy, whom I would like to thank very much for this invaluable input. Here is the alternative code he is describing, using an anonymous method instead of the TypeFilter:

class CmdFilterPerformance : IExternalCommand
{
  public CmdResult Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    try
    {
      Application app = commandData.Application;
      Document doc = app.ActiveDocument;
 
      Stopwatch sw = Stopwatch.StartNew();
 
      // f5 = f1 && f4 
      //    = f1 && (f2 || f3) 
      //    = family instance and (door or window)
 
      Autodesk.Revit.Creation.Filter cf
        = app.Create.Filter;
 
      //Filter f1 = cf.NewTypeFilter( 
      //  typeof( FamilyInstance ) );
 
      Filter f2 = cf.NewCategoryFilter(
        BuiltInCategory.OST_Doors );
      Filter f3 = cf.NewCategoryFilter(
        BuiltInCategory.OST_Windows );
 
      Filter f4 = cf.NewLogicOrFilter( f2, f3 );
      //Filter f5 = cf.NewLogicAndFilter( f1, f4 );
 
      //int n = doc.get_Elements( f5, openings );
 
      List<Element> openings = new List<Element>();
      doc.get_Elements( f4, openings );
 
      List<Element> openingInstances
        = openings.FindAll( delegate( Element element )
          {
            return !( element is Symbol );
          } );
      int n = openingInstances.Count;
 
      sw.Stop();
 
      Debug.WriteLine( string.Format(
        "Time to get {0} elements {1}",
        n, sw.ElapsedMilliseconds ) );
 
      return CmdResult.Succeeded;
    }
    catch( Exception ex )
    {
      message = ex.Message + ex.StackTrace;
      return CmdResult.Failed;
    }
  }
}

It really goes to show how extremely important testing on real life projects and scrupulous profiling and benchmarking is to ensure that you as a professional developer really deliver optimal quality to your clients. It also shows how easy it is for me to play around in an ivory tower and that my messages should always be taken with large grains of salt. And everybody else's too, of course. Guy has already pointed out some performance traps when blindly trusting Revit API filters to be fast in the past ... this one really brings the message across!

I am adding the complete Visual Studio solution here. This version 1.0.0.4 includes the four commands we discussed so far: CmdListWalls, CmdRelationshipInverter, CmdWallDimensions and the new CmdFilterPerformance.

Relationship Inverter

Moving away from the topic of geometry, I have another sample that I would like to share from the Revit API introductory workshop that I recently held. In this sample, we address the following topics:

• Using a Boolean combination of Revit API filters to find certain elements.
• Retrieving the hosted to host relationship between doors, windows, and walls.
• Inverting the relationship, i.e. determining the host to hosted one.

This sample also introduces some new little utility functions, such as ElementDescription() to return a string describing a given Revit element.

As said, we are interested in the relationship between door and window openings and the walls hosting them. The Revit API provides a one-way relationship from hosted element to its host in the form of the FamilyInstance.Host property, which returns the containing element if the family instance is contained within another element. In our case, the doors and windows are family instances, and the containing element is a wall.

In a first step, we create a Boolean combination of filters to select the elements we are interested in from the building model database. We do not need to retrieve the walls, because they do not provide any relationship information about their hosted elements. All we need is to access the doors and windows. These can be identified by having the class FamilyInstance and either door or window category. We can use a TypeFilter to match the class, and CategoryFilter instances for the categories. The category filters can be combined using a Boolean OR to match either door or window. The resulting filter can in turn be combined with the class filter using a Boolean AND. The result is described in the code below as

f5 = f1 && f4
   = f1 && (f2 || f3)
   = family instance and (door or window)

Once all doors and windows in the model have been retrieved, we can simply loop through them and query the host of each. For each host element id, we create a new entry into a dictionary using the host element id as a key and a list of all hosted element ids as its value. The elements being processed are also logged to the Visual Studio debug output window using the Debug.WriteLine() method provided by the very useful System.Diagnostics namespace.

At this point, we are actually already done. The resulting dictionary now implements the inverted relationship. We started out with each hosted element knowing its host, and now we have the dictionary with the host element id as key, and a list of ids of all its hosted elements as a value. All that remains to do is list this information in the debug output window, or use it in some other way.

Here is the code for this little command:

#region Namespaces
using System;
using System.Collections.Generic;
using System.Diagnostics;
using Autodesk.Revit;
using Autodesk.Revit.Elements;
using Autodesk.Revit.Parameters;
using CmdResult
  = Autodesk.Revit.IExternalCommand.Result;
#endregion // Namespaces
 
namespace BuildingCoder
{
  public class CmdRelationshipInverter
    : IExternalCommand
  {
    private Document m_doc;
 
    public static string PluralSuffix( int n )
    {
      return 1 == n ? "" : "s";
    }
 
    public static string DotOrColon( int n )
    {
      return 1 < n ? ":" : ".";
    }
 
    string ElementDescription( Element e )
    {
      // for a wall, the element name equals the 
      // wall type name, which is equivalent to the 
      // family name ...
      FamilyInstance fi = e as FamilyInstance;
      string fn = string.Empty;
      if( null != fi )
      {
        fn = fi.Symbol.Family.Name + " ";
      }
      return string.Format( "{0} {1}<{2} {3}>",
        e.Category.Name, fn,
        e.Id.Value.ToString(), e.Name );
    }
 
    string ElementDescription( ElementId id )
    {
      Element e = m_doc.get_Element( ref id );
      return ElementDescription( e );
    }
 
    private Dictionary<ElementId, List<ElementId>>
      getElementIds( List<Element> elements )
    {
      Dictionary<ElementId, List<ElementId>> dict =
        new Dictionary<ElementId, List<ElementId>>();
 
      string fmt = "{0} is hosted by {1}";
 
      foreach( FamilyInstance fi in elements )
      {
        ElementId id = fi.Id;
        ElementId idHost = fi.Host.Id;
 
        Debug.WriteLine( string.Format( fmt,
          ElementDescription( fi ),
          ElementDescription( idHost ) ) );
 
        if( !dict.ContainsKey( idHost ) )
        {
          dict.Add( idHost, new List<ElementId>() );
        }
        dict[idHost].Add( id );
      }
      return dict;
    }
 
    private void dumpHostedElements(
      Dictionary<ElementId, List<ElementId>> ids )
    {
      foreach( ElementId idHost in ids.Keys )
      {
        string s = string.Empty;
 
        foreach( ElementId id in ids[idHost] )
        {
          if( 0 < s.Length )
          {
            s += ", ";
          }
          s += ElementDescription( id );
        }
 
        int n = ids[idHost].Count;
 
        Debug.WriteLine(string.Format(
          "{0} hosts {1} opening{2}: {3}",
          ElementDescription( idHost ),
          n, PluralSuffix( n ), s ) );
      }
    }
 
    public CmdResult Execute(
      ExternalCommandData commandData,
      ref string message,
      ElementSet elements )
    {
      Application app = commandData.Application;
      m_doc = app.ActiveDocument;
 
      // f5 = f1 && f4 
      //    = f1 && (f2 || f3) 
      //    = family instance and (door or window)
      Autodesk.Revit.Creation.Filter cf
        = app.Create.Filter;
 
      Filter f1 = cf.NewTypeFilter(
        typeof( FamilyInstance ) );
 
      Filter f2 = cf.NewCategoryFilter(
        BuiltInCategory.OST_Doors );
      Filter f3 = cf.NewCategoryFilter(
        BuiltInCategory.OST_Windows );
 
      Filter f4 = cf.NewLogicOrFilter( f2, f3 );
      Filter f5 = cf.NewLogicAndFilter( f1, f4 );
 
      List<Element> openings = new List<Element>();
      int n = m_doc.get_Elements( f5, openings );
 
      // map with key = host element id and
      // value = list of hosted element ids:
      Dictionary<ElementId, List<ElementId>> ids =
        getElementIds( openings );
 
      dumpHostedElements( ids );
      m_doc = null;
 
      return CmdResult.Succeeded;
    }
  }
}

Here is a log file from a sample run. As you can see, we first traverse all the hosted elements and determine the hosting wall of each. These are inserted into the dictionary representing the inverse relationship, which dumps its contents using dumpHostedElements() before the command ends. Please excuse the long overflowing lines. To see them in full, you can copy and paste them into an editor such as notepad:

Doors M_Single-Flush <127252 0915 x 2134mm> is hosted by Walls <127248 Generic - 200mm>
Windows M_Fixed <127255 0406 x 0610mm> is hosted by Walls <127248 Generic - 200mm>
Windows M_Fixed <127258 0406 x 0610mm> is hosted by Walls <127248 Generic - 200mm>
Doors M_Single-Flush <127295 0915 x 2134mm> is hosted by Walls <127167 Generic - 200mm>
Doors M_Single-Flush <127331 0915 x 2134mm> is hosted by Walls <127167 Generic - 200mm>
Windows M_Fixed <127356 0406 x 0610mm> is hosted by Walls <127240 Generic - 200mm>
Windows M_Fixed <127411 0406 x 0610mm> is hosted by Walls <127240 Generic - 200mm>
Windows M_Fixed <127436 0406 x 0610mm> is hosted by Walls <127240 Generic - 200mm>
Windows M_Fixed <127462 0406 x 0610mm> is hosted by Walls <127215 Generic - 200mm>
Windows M_Fixed <127484 0406 x 0610mm> is hosted by Walls <127215 Generic - 200mm>
Windows M_Fixed <127502 0406 x 0610mm> is hosted by Walls <127215 Generic - 200mm>
Windows M_Fixed <127526 0406 x 0610mm> is hosted by Walls <127215 Generic - 200mm>
Walls <127248 Generic - 200mm> hosts 3 openings: Doors M_Single-Flush <127252 0915 x 2134mm>, Windows M_Fixed <127255 0406 x 0610mm>, Windows M_Fixed <127258 0406 x 0610mm>
Walls <127167 Generic - 200mm> hosts 2 openings: Doors M_Single-Flush <127295 0915 x 2134mm>, Doors M_Single-Flush <127331 0915 x 2134mm>
Walls <127240 Generic - 200mm> hosts 3 openings: Windows M_Fixed <127356 0406 x 0610mm>, Windows M_Fixed <127411 0406 x 0610mm>, Windows M_Fixed <127436 0406 x 0610mm>
Walls <127215 Generic - 200mm> hosts 4 openings: Windows M_Fixed <127462 0406 x 0610mm>, Windows M_Fixed <127484 0406 x 0610mm>, Windows M_Fixed <127502 0406 x 0610mm>, Windows M_Fixed <127526 0406 x 0610mm>

For your convenience, I am adding the complete Visual Studio solution here. This version 1.0.0.3 includes the three commands we discussed so far: CmdListWalls, CmdRelationshipInverter and CmdWallDimensions.