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.