The Building Coder

RoomsRoofs SDK Sample

Remaining on the track of geometrical topics, for the time being...

A common inquiry is how to determine the roof part of the boundary of a given room or space. Currently, Revit does not expose such an API, and there is no straightforward way to obtain this information. However, the new Revit SDK sample RoomsRoofs is provided to answer this question. It demonstrates how to check whether a room or space has a bounding roof, and determines all roof elements bounding a room or space from above.

Note that no new API functionality is used in this sample. The required calculations are done through a purely geometrical analysis. The sample queries the roof and the room or space for its geometry and then checks for intersections between the various elements. If the room or space intersects with a roof, it retrieves the room or space closed shell as a GeometryObjectArray, and extracts every solid element from it. It also determines the roof solid, and then feeds the two solids into the method AreSolidsCut( Solid, Solid ), which checks whether any of the solid faces overlap each other. You can also make use of AreSolidsCut() as a helper method for your own applications. The sample is not guaranteed to work with every possible configuration, so you may need to enhance it further for special cases.

The new sample is included in the standard Revit SDK distribution. It is currently also available for download from the ADN site in the Revit knowledgebase section under Revit 2009 Samples and Documents. For your convenience, I am also providing a copy of it right here.

It works in Revit Architecture, in which case the analysis is performed for rooms, and for Revit MEP, in which case spaces can be analysed, and is written in C#. Separate sample files are provided for these two situations. Here is the 3D view of the architectural sample file:

Here is the architectural sample file in plan view:

To run the sample, simply execute the external command. It determines all the rooms and spaces, calculates their roofs, and lists the analysis result in a dialogue box.

Wall Dimensions

After the diversion exploring the geometry related information and samples provided with the basic Revit SDK, let us finally get into an example of some own geometry related code. We present an algorithm to dimension an arbitrary Revit element containing a solid in its geometry. The implementation is tailored to handle wall elements, but the functionality can be applied to any other element containing geometry as well.

The idea is pretty simple, and possibly not awfully useful for real life, but geometrically elegant and interesting. We analyse the wall geometry and determine the maximum distance between all planar wall faces with parallel normal vectors. The maximum distance for any given normal vector is assumed to be the wall dimension in that direction. Non-planar faces are ignored. For each planar face, we determine its normal vector and origin. For all faces sharing the same normal vector, we collect all the origin points. After completing this collection process, we determine the maximal distance along the normal vector between all the faces sharing this normal. For a quadrilateral wall, the result will be the three dimensions one expects. For irregular walls with planar faces, additional dimensions will be detected in all directions perpendicular to two or more planar faces.

Here is the code for the external command and its support routines:

#region Header
//
// CmdWallDimensions.cs - determine wall dimensions 
// by iterating over wall geometry faces
//
// Copyright (C) 2008 by Jeremy Tammik, 
// Autodesk Inc. All rights reserved.
//
#endregion // Header
 
#region Namespaces
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;
using NormalAndOrigins
  = System.Collections.Generic.KeyValuePair
    < Autodesk.Revit.Geometry.XYZ
    , System.Collections.Generic.List
      <Autodesk.Revit.Geometry.XYZ>>;
#endregion // Namespaces
 
namespace BuildingCoder
{
  /// <summary>
  /// List dimensions for a quadrilateral wall with 
  /// openings. In this algorithm, we collect all 
  /// the faces with parallel normal vectors and 
  /// calculate the maximal distance between any 
  /// two pairs of them. This is the wall dimension 
  /// in that direction.
  /// </summary>
  class CmdWallDimensions
  {
    #region Geometry
    const double _eps = 1.0e-9;
 
    /// <summary>
    /// Check whether two real numbers are equal
    /// </summary>
    static bool DoubleEqual( double a, double b )
    {
      return Math.Abs( a - b ) < _eps;
    }
 
    /// <summary>
    /// Check whether two vectors are parallel
    /// </summary>
    static bool XyzParallel( XYZ a, XYZ b )
    {
      double angle = a.Angle( b );
      return _eps > angle
        || DoubleEqual( angle, Math.PI );
    }
    #endregion // Geometry
 
    /// <summary>
    /// Retrieve the planar face normal and origin 
    /// from all of the solid's planar faces and 
    /// insert them into the map mapping face normals
    /// to a list of all origins of different faces
    /// sharing this normal.
    /// </summary>
    /// <param name="m">Map mapping each normal vector 
    /// to a list of the origins of all planar faces 
    /// sharing this normal direction</param>
    /// <param name="solid">Input solid</param>
    void getFaceData(
      Dictionary<XYZ, List<XYZ>> m,
      Solid solid )
    {
      int i;
      FaceArray faces = solid.Faces;
      foreach( Face face in solid.Faces )
      {
        PlanarFace planarFace = face as PlanarFace;
        if( null != planarFace )
        {
          XYZ normal = planarFace.Normal;
          XYZ origin = planarFace.Origin;
          List<XYZ> normals = new List<XYZ>( m.Keys );
          i = normals.FindIndex(
            delegate( XYZ v )
            {
              return XyzParallel( v, normal );
            } );
          if( -1 == i )
          {
            Debug.WriteLine( string.Format(
              "Face at {0} has new normal {1}",
              Util.PointString( origin ),
              Util.PointString( normal ) ) );
            m.Add( normal, new List<XYZ>() );
            m[normal].Add( origin );
          }
          else
          {
            Debug.WriteLine( string.Format(
              "Face at {0} normal {1} matches {2}",
              Util.PointString( origin ),
              Util.PointString( normal ),
              Util.PointString( normals[i] ) ) );
            m[normals[i]].Add( origin );
          }
        }
      }
    }
 
    public CmdResult Execute(
      ExternalCommandData commandData,
      ref string message,
      ElementSet elements )
    {
      Application app = commandData.Application;
      Document doc = app.ActiveDocument;
      Selection sel = doc.Selection;
      Options o = app.Create.NewGeometryOptions();
      // map planar face normals to face origins:
      Dictionary<XYZ, List<XYZ>> m
        = new Dictionary<XYZ, List<XYZ>>();
      string s, msg = string.Empty;
      int i;
      foreach( RvtElement e in sel.Elements )
      {
        Wall wall = e as Wall;
        if( null != wall )
        {
          s = string.Format( "Wall <{0} {1}>:",
            wall.Name, wall.Id.Value );
          Debug.WriteLine( s );
          if( 0 < msg.Length ) { msg += "\n\n"; }
          msg += s;
          GeoElement ge = wall.get_Geometry( o );
          GeometryObjectArray objs = ge.Objects;
          foreach( GeometryObject obj in objs )
          {
            Solid solid = obj as Solid;
            if( null != solid )
            {
              getFaceData( m, solid );
            }
          }
          int j, n;
          double d, dmax;
          foreach( NormalAndOrigins pair in m )
          {
            dmax = 0;
            XYZ normal = pair.Key.Normalized;
            List<XYZ> pts = pair.Value;
            n = pts.Count;
            if( 1 == n )
            {
              s = string.Format(
                "Only one wall face in "
                + "direction {0} found.",
                Util.PointString( normal ) );
            }
            else
            {
              for( i = 0; i < n - 1; ++i )
              {
                for( j = i + 1; j < n; ++j )
                {
                  XYZ v = pts[i].Subtract( pts[j] );
                  d = v.Dot( normal );
                  if( d > dmax )
                  {
                    dmax = d;
                  }
                }
              }
              s = string.Format(
                "Max wall dimension in "
                + "direction {0} is {1} feet.",
                Util.PointString( normal ),
                Util.RealString( dmax ) );
            }
            Debug.WriteLine( s );
            msg += "\n" + s;
          }
          m.Clear();
        }
      }
      if( 0 == msg.Length )
      {
        msg = "Please select some walls.";
      }
      Util.InfoMsg( msg );
      return CmdResult.Succeeded;
    }
  }
}

We use regions to structure the code. It allows us to collapse bits of code that we are currently not interested in to reduce screen clutter and improve the overview. The main geometrical analysis is implemented in getFaceData(). It traverses the solid passed in and collects all the planar face normal vectors and origins, using the normals as dictionary keys, and creating lists of origin points as dictionary values. Once this information has been assembled, we traverse it to format it into a string to be presented in a message box, as well as listing it in the Visual Studio debug output window.

The namespace is BuildingCoder, and the command name CmdWallDimensions, so the information to add to Revit.ini is something like this:

[ExternalCommands]
ECCount=1
ECName1=Wall Dimensions
ECDescription1=Extract wall solid and list all its dimensions
ECAssembly1=C:\bin\BuildingCoder.dll
ECClassName1=BuildingCoder.CmdWallDimensions

Here is a sample wall to run it on, created by the external command defined by Lab2_0_CreateLittleHouse in the Revit API introduction labs:

Here is the result of selecting the wall and running the command:

This is the log data printed to the Visual Studio debug output window generated during the process, to help understand how the faces are analysed one by one to determine whether their normal either matches an existing or defines a new one:

Wall <Generic - 200mm 127248>:
Face at (0,-0.33,0) has new normal (0,-1,0)
Face at (12.98,0.33,0) has new normal (-1,0,0)
Face at (0,-0.33,0) has new normal (0,0,-1)
Face at (23.29,0,0) normal (1,0,0) matches (-1,0,0)
Face at (22.97,-0.33,13.12) normal (0,0,1) matches (0,0,-1)
Face at (-0.33,13.12,0) normal (-1,0,0) matches (-1,0,0)
Face at (9.98,0.33,7) normal (1,0,0) matches (-1,0,0)
Face at (12.98,0.33,7) normal (0,0,-1) matches (0,0,-1)
Face at (5.08,-0.33,3.94) normal (1,0,0) matches (-1,0,0)
Face at (5.08,-0.33,5.94) normal (0,0,-1) matches (0,0,-1)
Face at (6.41,-0.33,5.94) normal (-1,0,0) matches (-1,0,0)
Face at (6.41,-0.33,3.94) normal (0,0,1) matches (0,0,-1)
Face at (16.56,-0.33,3.94) normal (1,0,0) matches (-1,0,0)
Face at (16.56,-0.33,5.94) normal (0,0,-1) matches (0,0,-1)
Face at (17.89,-0.33,5.94) normal (-1,0,0) matches (-1,0,0)
Face at (17.89,-0.33,3.94) normal (0,0,1) matches (0,0,-1)
Face at (0,0.33,0) normal (0,1,0) matches (0,-1,0)
Max wall dimension in direction (0,-1,0) is 0.66 feet.
Max wall dimension in direction (-1,0,0) is 18.22 feet.
Max wall dimension in direction (0,0,-1) is 13.12 feet.
Wall <Generic - 200mm 127248>:
Max wall dimension in direction (0,-1,0) is 0.66 feet.
Max wall dimension in direction (-1,0,0) is 18.22 feet.
Max wall dimension in direction (0,0,-1) is 13.12 feet.

Geometry Viewers

The previous post provided an overview of the Revit geometry library and very briefly mentioned some geometry viewers provided in the Revit SDK samples. We will discuss these a little bit more before moving on to some own example code dealing with geometry.

The Revit SDK currently includes the following viewers:

• AnalyticalViewer
• ElementViewer
• RoomViewer
• RevitViewer
• ObjectViewer

All the viewers query a selected Revit element for some specific geometry, traverse it, break it down into simple line segments, and render those into a .NET System.Windows.Forms PictureBox. They can all be classified as pretty basic samples. The first four of these are all located in the subdirectory Viewers and are implemented in VB. They were introduced early on in the Revit API, with version 8.0. Of these four, the RevitViewer is a helper class, which implements the actual viewer window which is used by the other three to present three different views of certain subsets of the building model. ObjectViewer was introduced later, in the Revit 9.0 SDK, is written in C#, and defines its own rendering window. Below is an example of the form defined by RevitViewer; in this case, it is being driven by the ElementViewer sample and displaying a wall with a door and two little windows in it. The wall has been generated by the external command defined by Lab2_0_CreateLittleHouse in the Revit API introduction labs. The form looks identical when driven by the AnalyticalViewer and RoomViewer samples, only the content displayed differs:

 

The AnalyticalViewer is for Revit Structure, to view the analytical building model. The analytical model is generally a simplified approximation of the building structure for structural analysis purposes, which is of most interest to the structural engineer. Revit Structure maintains the analytical model in parallel with the physical model, which is what architects and most other people are interested in.

ElementViewer is designed for all flavours of Revit and displays the standard element geometry.

RoomViewer is a viewer for displaying the two-dimensional outline of a room boundary.

Just like the three viewers, just discussed, ObjectViewer demonstrates viewing elements. It allows the user to select between the analytical and physical model, and also which view to display. You might thus say that it is a combination of the AnalyticalViewer and the ElementViewer with some additional features.

 

ObjectViewer includes both generic functionality usable in all Revit flavours, as well as some Revit Structure specific functionality. It displays a selected single element in a preview window and retrieves geometry from either the analytical or physical model. It also includes some additional useful odds and ends such as defining an own error message exception handling class and some unit handling functionality. ObjectViewer was originally introduced in Revit 9. Another very similar sample named ObjectViewerII was introduced in 9.1. ObjectViewerII was removed in the 2008.2 SDK update, being very similar to ObjectViewer.

For all of the viewers, the steps to run are similar: simply select the element whose geometry or the room whose boundary to display and start the external command. The analytical viewer will check whether any analytical model is available, which requires Revit Structure functionality. In the case of the ObjectViewer, all display views are listed, the detail level can be selected, and analytical and physical model can be switched.

Now that we have looked a bit at some basic information on the Revit geometry and SDK samples, let us finally move on to some own example code dealing with geometry.

Geometry Library

In a comment on What Next, Rod Howarth suggested looking a bit at functionality that involves using geometry, location points and other modelling based stuff. I think this is a brilliant idea; it fits in well with the introductory material that we have discussed so far, and constitutes a logical and interesting next step in exploring the Revit API. Before diving into any own example code dealing with geometry, let us look a bit first at the Revit geometry library itself, and then the samples already at our disposal, provided in the SDK. I will also be covering this material in my session DE205-3 Enhancing Your Revit Add-In on Wednesday December 3. 2008 at Autodesk University from 10:15 - 11:45 am.

The Geometry library in Revit API includes a set of classes representing commonly used geometry, such as points, lines, curves, and surfaces. It also includes classes representing solids, whose boundary information can be queried, such as edges and faces. It includes point, vector, and matrix calculations, special functions to find intersection of two geometric objects, and much more.

The Revit API includes a Geometry namespace encapsulating a geometry library providing geometrical calculation functionality. It is similar to ObjectARX AcGe library. The library works with temporary objects in memory, i.e. non database resident objects. Some of the objects can be created through the API using methods on the Application class in the Autodesk.Revit.Creation namespace. Others cannot yet be created through the API and are only provided when existing database elements are queried for their geometry generated internally by the Revit kernel.

All geometrical classes are now reference types derived from APIObject, object, or enumeration interfaces. The XYZ, UV, and BoundingBoxUV classes were value types in 2008 and earlier versions, but are so no longer.

The figure provided in "Revit API Diagram.dwf" in the Revit SDK illustrates the classes defined in the Revit API Geometry namespace. The geometry library provides both simple and complex geometry classes. UV and XYZ represent a point and a vector in 2D and 3D, respectively. Transform offers basic matrix operations, such as translation, rotation and scaling. The Curve class provides a base class and common functionality for Line, Arc, Ellipse and the more complex subclass NurbSpline. The Revit API Geometry namespace also includes solid representations including Solid, Face, and Edge. These are used to retrieve geometry information for architectural elements in Revit.

Non APIObject classes: In Revit, UV and XYZ are used to represent points and vectors, 2D and 3D respectively. Unlike the more complex geometry classes, they are not derived from APIObject. Unlike ObjectARX's AcGe library, there is no strict distinction between point and vector. You can use them interchangeably depending on the context of the actual usage. UV could be a parameter on a surface. You will find many usages of these classes in the Revit SDK samples. Some classes provide static properties that define convenient predefined data. XYZ, for example, defines XYZ.BasisX as a typical vector representing the X axis, i.e., (1,0,0). Similarly, BasisY and BasisZ define the Y and Z axes, and XYZ.Zero defines the origin (0,0,0). You can find the corresponding 2D properties on UV as well.

APIObject classes: Some of the classes derived from APIObject are BoundingBoxXYZ, IntersectionResult, MeshTriangle, Options, Plane, Reference and Transform. Transformations are represented by the Transform class, which can be compared to a transformation matrix. You can set up a transformation for translation, rotation, and reflection, and perform such operations on points and vectors. Transform defines an Identity property.

GeometryObject classes: Some of the classes derived from GeometryObject are Element, which is a sort of geometry container class, Instance, which represents repeatable instances of symbol geometry, and the "real" geometry classes Curve, Edge, Face, Mesh, Profile, and Solid. The Autodesk.Revit.Geometry.Element class is not to be confused with the Autodesk.Revit.Element one. The latter represents a Revit database element, the former a geometrical one, and they are completely different.

So, the geometry Element class is a container for geometric primitives. It is generated from a database element when its geometry is queried. The database element uses a parametric description to define its geometry. The main property of the Element class is Objects, which provides access to the geometric primitives contained in the element. In other words, the geometry element is a container for the database element geometry, and provides the interface and temporary repository to query a building element for its geometry.

The Instance class represents an instance of symbol geometry, which is positioned by this database element. Some of its important properties and methods are:

• Symbol, returning the symbol element that this object is referring to
• SymbolGeometry, the geometric representation of the symbol
• Transform, an affine transformation from the local coordinate space
• Transformed, which transforms this instance and returns the result

The Curve class represents a parametric curve and is the base class for arc, ellipse, line, and nurb spline. It has the typical properties and methods of a geometric curve class such as ApproximateLength, Length, ComputeDerivatives, Distance, Evaluate, Intersect, IsInside, etc. One commonly used method is Tessellate, which returns a set of line segments approximating the curve. This is used by the simple geometry viewers included in the Revit SDK, which reduce all geometry to line segments and display the result in a .NET form.

Similarly, the Face class represents a parametric face. It is a base class for more specialised derived classes such as ConicalFace, CylindricalFace, HermiteFace, PlanarFace, RevolvedFace and RuledFace. It provides a Triangulate method to simplify complex curved geometry into a collection of simple planar triangles approximating it.

The Solid is a top level representation of a database element solid geometry. From the solid, we can traverse the solid's boundary representation by querying it for its faces and edges. We can also simplify the solid by calling the Tesselate method to obtain simple triangles approximating the geometry, which may initially include much more complex non-planar surfaces.

The Revit API does not provide full coverage of geometry creation. For instance, there is currently no way to create face from scratch in the Revit API. Generally, making a face is a lengthy process: you need to define the surface and all the edges and how it relates to all the other faces in the solid and the model at large. In fact, inside Revit, faces are very rarely created by hand, instead internal geometry kernel routines are used. At the moment, there is no external API to these routines, and designing one is hard too. So, for now you can only obtain a face from an existing model element. For instance, this satisfies the need for calculating the closest point to an existing object. The Revit geometry API is not suited for generic geometry calculations with no relation to the building model. One would expect that developers requiring this kind of computation have their own in-house math library anyway.

To retrieve Revit element geometry, you use the Element.Geometry property, which is accessed through the get_Geometry() method in C#. The various viewers such as the VB ElementViewer and C# ObjectViewer in the Revit SDK samples demonstrate this. They traverse all the geometry and simplify it down to simple line segments, which are then displayed in a graphics window in a .NET form. The geometry traversal may become recursive, because some geometrical elements represent instances of other geometry, with a transformation applied to it.

Generally, the geometry traversal will start at the top level solid and then iterate down through its faces and edges. The best way to understand this properly is to run the ElementViewer or ObjectViewer in the debugger and track the traversal through the geometry of some simple element.

In the next post, I plan to briefly describe the different geometry viewers included in the Revit SDK samples, and then move on to some own example code dealing with geometry.

Units

In the previous post, we noted that the area parameter for a wall had a numerical value of 283.65 on one hand, but a string representation of '26.352 m²' on the other. The reason for these two different values is that Revit internally works with a fixed set of database units for different measurement types. These internal database units cannot be changed. All raw database values obtained from attributes will always be returned and expected in database units. Some of the internal database length units are imperial. The database unit for length is feet, and areas are stored in square feet. The units used are not the standardised SI units according to the International System of Units SI.

Similarly, if we examine the thickness of a 200 mm wall, e.g. one using the system family 'Basic Wall' and the type 'Generic - 200.0 mm', its thickness is available in the type parameter 'width'. It appears to have the value 200 mm in the user interface, if set up to display metric length units. Looking at the actual value of the underlying parameter, however, returns a completely different number, something like 0.6561. 0.6561 feet is 0.6561 * 12 = 7.8732 inches, which corresponds to 7.8732 * 25.4 = 199.97928 millimetres.

The user interface settings affecting the display of units in Revit can be queried through the API. The ProjectUnit SDK sample demonstrates how to do this. The units displayed in the user interface can be queried through the read-only Document.DisplayUnitSystem property. The Parameter.DisplayUnitType property determines how any individual parameter is displayed in the user interface. The DisplayUnitType enumeration lists all the supported display unit types.

It can sometimes be tricky to figure out exactly what units Revit is using internally, for instance when analysing things like point, line and area loads in Revit Structure. For these loads, the units used are in terms of N and m, unlike other parameters and co-ordinates which use feet for all lengths.

The good news, and the main message of this post, is that you do not really have to care what units Revit is using internally. All you need to do is some little research to determine a valid conversion factor. You can enter the unit value for whatever you are interested in in the user interface, and then check what the API reports. It will always be in the same internal units. This can then be used as a conversion factor for that specific unit. It works consistently. Possibly you may refine this depending on the metric or imperial Revit setting, but the factors are the same and consistent.

So the simplest thing to do to determine the conversion factor to use is to set the parameter to 1 in the user interface and then observe the value returned by the API, which gives the conversion factor between the two.

I am appending a small utility class UnitConversion.cs which may be of use in this context, even if just to give you a first impression of how these issues may be handled. I am not saying that this is the optimal solution. It includes some useful constants and stems from the Midas Link Revit Structure sample application which is available including source code on the ADN web site. By the way, the updated MidasLink version for Revit 2009 has just been posted to ADN, in case you are interested. Please excuse the fact that the source code lines exceed the blog display width. To obtain and review the full source code, please simply copy and paste it to notepad or some other editor.

// (C) Copyright 2003-2007 by Autodesk, Inc.
//
// Permission to use, copy, modify, and distribute this software in
// object code form for any purpose and without fee is hereby granted,
// provided that the above copyright notice appears in all copies and
// that both that copyright notice and the limited warranty and
// restricted rights notice below appear in all supporting
// documentation.
//
// AUTODESK PROVIDES THIS PROGRAM "AS IS" AND WITH ALL FAULTS.
// AUTODESK SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTY OF
// MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE. AUTODESK, INC.
// DOES NOT WARRANT THAT THE OPERATION OF THE PROGRAM WILL BE
// UNINTERRUPTED OR ERROR FREE.
//
// Use, duplication, or disclosure by the U.S. Government is subject to
// restrictions set forth in FAR 52.227-19 (Commercial Computer
// Software - Restricted Rights) and DFAR 252.227-7013(c)(1)(ii)
// (Rights in Technical Data and Computer Software), as applicable.
//
 
using System;
using System.Collections.Generic;
using System.Text;
using System.Collections;
using System.Windows.Forms;
using System.Diagnostics;
 
using Autodesk.Revit;
using Autodesk.Revit.Elements;
using Autodesk.Revit.Enums;
using Autodesk.Revit.Parameters;
 
namespace Revit.MGT
{
  /// <summary>
  /// Unit conversion - convert values from standard units to given units.
  /// </summary>
  public class UnitConversionFactors
  {
    #region Class Member Variables
 
    /// <summary>
    /// Standard units
    /// </summary>
    private string m_FromUnits;
 
    /// <summary>
    /// Given units
    /// </summary>
    private string m_ToUnits;
 
    /// <summary>
    /// true: conversion available for given units
    /// </summary>
    private bool m_RatioSetUpSucceeded;
 
    /// <summary>
    /// To store length ratio
    /// </summary>
    private double m_LengthRatio;
 
    /// <summary>
    /// To store point load ratio
    /// </summary>
    private double m_PointLoadRatio;
 
    /// <summary>
    /// To store point load moment ratio
    /// </summary>
    private double m_PointLoadMomentRatio;
 
    /// <summary>
    /// To store line load ratio
    /// </summary>
    private double m_LineLoadRatio;
 
    /// <summary>
    /// To store line moment ratio
    /// </summary>
    private double m_LineMomentRatio;
 
    /// <summary>
    /// To store area load ratio
    /// </summary>
    private double m_AreaLoadRatio;
 
    /// <summary>
    /// To store stress ratio
    /// </summary>
    private double m_StressRatio;
 
    /// <summary>
    /// To store unit weight ratio
    /// </summary>
    private double m_UnitWeightRatio;
 
    /// <summary>
    /// To store point spring ratio
    /// </summary>
    private double m_PointSpringRatio;
 
    /// <summary>
    /// To store rotational point spring ratio
    /// </summary>
    private double m_RotationalPointSpringRatio;
 
    #endregion
 
 
    #region Class Public Properties
    /// <summary>
    /// Get FromUnits
    /// </summary>
    public string FromUnits
    {
      get
      {
        return m_FromUnits;
      }
    }
 
    /// <summary>
    /// Get ToUnits
    /// </summary>
    public string ToUnits
    {
      get
      {
        return m_ToUnits;
      }
    }
 
    /// <summary>
    /// Get RatioSetUpSucceeded
    /// </summary>
    public bool RatioSetUpSucceeded
    {
      get
      {
        return m_RatioSetUpSucceeded;
      }
    }
 
    /// <summary>
    /// Get length ratio
    /// </summary>
    public double LengthRatio
    {
      get
      {
        return m_LengthRatio;
      }
    }
 
    /// <summary>
    /// Get point load ratio
    /// </summary>
    public double PointLoadRatio
    {
      get
      {
        return m_PointLoadRatio;
      }
    }
 
    /// <summary>
    /// Get point load moment ratio
    /// </summary>
    public double PointLoadMomentRatio
    {
      get
      {
        return m_PointLoadMomentRatio;
      }
    }
 
    /// <summary>
    /// Get line load force ratio
    /// </summary>
    public double LineLoadForceRatio
    {
      get
      {
        return m_LineLoadRatio;
      }
    }
 
    /// <summary>
    /// Get line load moment ratio
    /// </summary>
    public double LineLoadMomentRatio
    {
      get
      {
        return m_LineMomentRatio;
      }
    }
 
    /// <summary>
    /// Get area load ratio
    /// </summary>
    public double AreaLoadRatio
    {
      get
      {
        return m_AreaLoadRatio;
      }
    }
 
    /// <summary>
    /// Get stress ratio
    /// </summary>
    public double StressRatio
    {
      get
      {
        return m_StressRatio;
      }
    }
 
    /// <summary>
    /// Get unit weight ratio
    /// </summary>
    public double UnitWeightRatio
    {
      get
      {
        return m_UnitWeightRatio;
      }
    }
 
    /// <summary>
    /// Get point sprint ratio
    /// </summary>
    public double PointSpringRatio
    {
      get
      {
        return m_PointSpringRatio;
      }
    }
 
    /// <summary>
    /// Get rotational point spring ratio
    /// </summary>
    public double RotationalPointSpringRatio
    {
      get
      {
        return m_RotationalPointSpringRatio;
      }
    }
    #endregion
 
 
    #region Class Constructor
    /// <summary>
    /// Constructor
    /// </summary>
    /// <param name="lengthUnit">length unit</param>
    /// <param name="forceUnit">forth unit</param>
    public UnitConversionFactors(
      string lengthUnit,
      string forceUnit )
    {
      // Initialize standard factors
      InitializeConversionFactors();
 
      // Get length conversion factor
      double lenFactor = GetLengthConversionFactor(lengthUnit);
      if (!m_RatioSetUpSucceeded)
      {
        return;
      }
 
      // Get Force conversion factor
      double forceFactor = GetForceConversionFactor(forceUnit);
      if (!m_RatioSetUpSucceeded)
      {
        return;
      }
 
      // Set up all the conversion factors
      m_ToUnits = lengthUnit + '-' + forceUnit;
      SetUnitConversionFactors(lenFactor, forceFactor);
    }
    #endregion
 
 
    #region Class Implementation
    /// <summary>
    /// Initialize factor to convert internal units to standard ft, kips.
    /// </summary>
    private void InitializeConversionFactors()
    {
      // Internally Revit stores length in feet and other quantities in metric units.
      // Thus the derived unit for force is stored in a non-standard unit: kg-ft/s**2.
      // For example, m_PointLoadRatio below equals 1 (kip) / 14593.90 (kg-ft/s**2)
      m_FromUnits = "ft-kips";
      m_ToUnits = "";
      m_LengthRatio = 1;
      m_PointLoadRatio = 0.00006852176585679176;
      m_PointLoadMomentRatio = 0.00006852176585679176;
      m_LineLoadRatio = 0.00006852176585679176;
      m_LineMomentRatio = 0.00006852176585679176;
      m_AreaLoadRatio = 0.00006852176585679176;
      m_StressRatio = 0.00006852176585679176;
      m_UnitWeightRatio = 0.00006852176585679176;
      m_PointSpringRatio = 0.00006852176585679176;
      m_RotationalPointSpringRatio = 0.00006852176585679176 * 180 / Math.PI;   // Revit uses degrees, Midas uses radians
      m_RatioSetUpSucceeded = false;
    }
 
    /// <summary>
    /// Get length conversation factor
    /// </summary>
    /// <param name="lengthUnit">length unit type</param>
    /// <returns>length conversation factor</returns>
    private double GetLengthConversionFactor(
      string lengthUnit )
    {
      bool unitAvailable = true;
      double lenFac = 0;
 
      switch (lengthUnit)
      {
        case "ft":
          lenFac = 1;
          break;
        case "in":
          lenFac = 12;
          break;
        case "m":
          lenFac = 0.3048;
          break;
        case "cm":
          lenFac = 30.48;
          break;
        case "mm":
          lenFac = 304.8;
          break;
        default:
          unitAvailable = false;
          break;
      }
      m_RatioSetUpSucceeded = unitAvailable;
      return lenFac;
    }
 
    /// <summary>
    /// Get force conversation factor
    /// </summary>
    /// <param name="forceUnit">force unit</param>
    /// <returns>force conversation factor</returns>
    private double GetForceConversionFactor(
      string forceUnit )
    {
      bool unitAvailable = true;
      double forceFac = 0;
 
      switch (forceUnit)
      {
        case "kips":
          forceFac = 1;
          break;
        case "lbf":
          forceFac = 1000;
          break;
        case "kN":
          forceFac = 4.4482216152605;
          break;
        case "N":
          forceFac = 4448.2216152605;
          break;
        case "tonf": // metric tonne
          forceFac = 4.4482216152605 * 0.101971999794;
          break;
        case "kgf":
          forceFac = 4448.2216152605 * 0.101971999794;
          break;
        default:
          unitAvailable = false;
          break;
      }
      m_RatioSetUpSucceeded = unitAvailable;
      return forceFac;
    }
 
    /// <summary>
    /// Set length and force unit conversation factor
    /// </summary>
    /// <param name="lenFac">length unit factor</param>
    /// <param name="forceFac">force unit factor</param>
    private void SetUnitConversionFactors(
      double lenFac,
      double forceFac )
    {
      m_LengthRatio *= (lenFac);
      m_PointLoadRatio *= (forceFac);
      m_PointLoadMomentRatio *= (forceFac * lenFac);
      m_LineLoadRatio *= (forceFac / lenFac);
      m_LineMomentRatio *= (forceFac);
      m_AreaLoadRatio *= (forceFac / lenFac / lenFac);
      m_StressRatio *= (forceFac / lenFac / lenFac);
      m_UnitWeightRatio *= (forceFac / lenFac / lenFac / lenFac);
      m_PointSpringRatio *= (forceFac / lenFac);
      m_RotationalPointSpringRatio *= (forceFac * lenFac);
    }
    #endregion
  }
}

Selecting all Walls

Now that we have covered the basics, let us get into some small examples of day to day issues that arise. I recently gave a Revit API introductory workshop. The first little sample add-in we wrote together as a first step to exploring API access to the Revit BIM selects all wall elements in the database and lists the area and length of each. This provides an opportunity to discuss a number of interesting details, such as some of the debugging support included in the .NET framework, the handling of units in Revit, parameter access and location definition on Revit database elements, etc.

Let us discuss some elements of interest in the code before actually presenting it.

One .NET framework feature that I suggest exploring is the Debug namespace. We use it below to comfortably print out information to the Visual Studio debug output window using Debug.WriteLine(). Of course, this is only useful in a debugging context, but then it is much more comfortable than formatting stuff into a string for presentation in a message box, in which the user has the onerous task of clicking OK, and which is less handy to search for text in or copy and paste from.

I make use of 'using' statements to minimise code bloat and make the code as readable as possible. I also make use of aliases to define handy short cuts such as CmdResult instead of the rather hefty IExternalCommand.Result. In the code below, I avoid a statement using the entire Autodesk.Revit.Geometry namespace, since that would create an ambiguity between Autodesk.Revit.Element and Autodesk.Revit.Geometry.Element. Instead, I just create an alias for Autodesk.Revit.Geometry.XYZ and avoid pulling in all the rest of that namespace.

The code below demonstrates a simple use of the Revit 2009 filtered element access to access all wall elements in the building model, which is vastly faster than the element iteration in 2008.

We extract the wall area from the built-in parameter HOST_AREA_COMPUTED. Further down, you will note that this produced slightly unexpected results, so we also added code to check each wall length by retrieving the start and end point of its location curve.

Here is the complete code of this little external command:

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;
using XYZ = Autodesk.Revit.Geometry.XYZ;
 
namespace SelectWalls
{
  public class Util
  {
    static public string RealString( double a )
    {
      return a.ToString( "0.##" );
    }
  }
 
  public class Command : IExternalCommand
  {
    public CmdResult Execute(
      ExternalCommandData commandData,
      ref string message,
      ElementSet elements )
    {
      Application app = commandData.Application;
      Document doc = app.ActiveDocument;
      Type t = typeof( Wall );
      Filter f = app.Create.Filter.NewTypeFilter( t );
      List<Element> walls = new List<Element>();
      int n = doc.get_Elements( f, walls );
      foreach( Wall wall in walls )
      {
        Parameter param = wall.get_Parameter(
          BuiltInParameter.HOST_AREA_COMPUTED );
        double a = ( ( null != param )
          && (StorageType.Double == param.StorageType) )
          ? param.AsDouble()
          : 0.0;
        string s = ( null != param )
          ? param.AsValueString()
          : "null";
        LocationCurve lc = wall.Location as LocationCurve;
        XYZ p = lc.Curve.get_EndPoint( 0 );
        XYZ q = lc.Curve.get_EndPoint( 1 );
        double l = q.Distance( p );
        string format
          = "Wall <{0} {1}> length {2} area {3} ({4})";
        Debug.WriteLine( string.Format( format,
          wall.Id.Value.ToString(), wall.Name,
          Util.RealString( l ), Util.RealString( a ),
          s ) );
      }
      return CmdResult.Succeeded;
    }
  }
}

We need some walls to run this on. As a sample model, we can use the little house created by the Lab2_0_CreateLittleHouse command in the code accompanying the Revit API introduction, which looks like this in plan view:

Here is the 3D view of the sample model:

Running the command in this sample produces the following in the debug output window:

Wall <127145 Generic - 200mm> length 22.97 area 283.65 (26.352 m²)
Wall <127146 Generic - 200mm> length 13.12 area 172.22 (16.000 m²)
Wall <127147 Generic - 200mm> length 22.97 area 301.39 (28.000 m²)
Wall <127148 Generic - 200mm> length 13.12 area 163.61 (15.200 m²)

There are various items of interest here. One of them stems from the fact when dealing with length and area, we need to consider the units being used. This will be the topic of a future posting.

Another question is this: Why do we see four different wall areas in the list? The little house is rectangular, so we would expect the walls and thus their areas to be pairwise identical. In fact, this is what prompted us to list the location line length as well, where we note that these are indeed pairwise identical. The reason has to do with the Revit product and the way it handles the wall joins at the corners. If we set up all the walls to connect to their neighbours using a mitered wall join, then the reported areas will be identical for walls of equal length.

What Next?

Now that we have got the getting started material out of the way, let us embark on the great adventure of free unstructured day to day blogging. If you think there is anything still missing for the getting started material, please let me know. Also, please let me know if you have any comments on the material I post or wishes and ideas for other subjects that I have not yet touched. I can obviously make no guarantees about anything, especially not that I will actually be able to address any requests or questions raised. The idea behind this blog is for me to be able to chit-chat about anything that I find interesting and that may be of use to the wider community and participate in a constructive dialogue on the Revit API. On the other hand, I do have a day time job that I need to take care of first. I will also be away now and then, on holiday or involved in other commitments where I have limited Internet access, so please bear with me if it occasionally takes a while for me to reply to some input.

One of the things I could talk about next are the labs included with the Revit API introductory material mentioned in the post on Getting Started with the Revit API. Another potential topic might be looking into the Revit SDK samples in more detail. I might do that, since I have to prepare a presentation on that topic for Autodesk University in Las Vegas in December. Finally, and most attractive for me at the moment, is to just talk about anything that comes to mind.

A nice little subject of that kind is looking into the samples that I created interactively with the participants in a recent Revit API introductory workshop. As a first step to exploring API access to the Revit BIM, we implemented a little plug-in which selects all wall elements in the database and lists the area and length of each.

This gave us an opportunity to discuss a number of interesting details, such as some debugging support included in the .NET framework, the handling of units in Revit, parameter access and location definition on Revit database elements, etc.

Debugging a Revit Add-In

I often hear the question how to unload a Revit add-in. Unfortunately, this is not possible, due to the fundamental .NET framework mechanisms used to load and manage the plug-ins. Revit manages one AppDomain which is used to load all add-in classes.

It would theoretically be possible to unload the entire AppDomain to remove the loaded add-ins. I once tried to implement a system to unload a Revit plug-in by implementing a cascaded pair of IExternalCommand classes. In the first one A, which I registered as an external command in Revit.ini, I set up my own AppDomain, into which I loaded the second class B. When invoking the command implemented by A, I was able to trap the arguments passed in to A.Execute() and invoke and pass them on to B.Execute() without problems. I was also able to delete the AppDomain I had created, thus removing B from the system memory. Unfortunately, something in the .NET framework was still keeping the secondary assembly DLL file locked, so I was unable to overwrite or delete it.

But what I really want to point out here is that there is normally no need to unload Revit add-ins for debugging purposes, because running Revit from the debugger, opening a ready-prepared test model and loading and executing the add-in can be achieved using just a handful of keystrokes and in a matter of a very few seconds. Let us go through the steps for setting up such a system one by one.

For completeness sake, and to ensure that we are really all on the same page, I suggest we start from scratch with a brand new Revit add-in project. That means that we will be going through the same steps as those described in the DevTV presentation and webcast recording mentioned in the getting started post. Here is the short version of the description to set up a new Revit add-in:

• Start Visual Studio 2005.
• Create a new VB or CS .NET project: File > New > Project... > Visual Basic or Visual C# > Class Library.
• Specify the project name and location, for instance DebugTest and C:\tmp\revit.
• This generates a complete skeleton application.
• Rename the class from Class1 to Command, simply to follow a common Revit add-in practice. I do this by clicking on the file name in the solution explorer and renaming that. It automatically renames the class contained in it as well.

From here on, there are some small differences between C# and VB. For C#, we can proceed as follows:

• Remove the unneeded references to System.Data and System.Xml.
• Add a reference to RevitAPI.dll by right clicking on the project references in the solution explorer and selecting Add Reference.
• Do not forget to set the 'Copy Local' flag to False. You do so by opening the properties of RevitAPI.dll. See The SDK Samples Solution for a more detailed explanation of this step.
• Remove the unneeded using statements for System.Collections.Generic and System.Text in the command class source file.
• Add a line at the top saying 'using Autodesk.Revit;'. Note that Intellisense jumps in as soon as you have typed 'Autodesk.', so you almost never need to fully type out any identifier.
• Specify the IExternalCommand parent class for Command by adding ": IExternalCommand" after "public class Command". Note here as well that Intellisense saves you from typing anything but the first few characters of the class name.
• Implement the Execute() method by right clicking on IExternalCommand in the source code and selecting Implement Interface > Implement Interface. This generates the source code for Execute(), which I generally reformat a little to make it more readable.
• Replace the automatically generated exception throwing code by a valid return value, e.g. "return IExternalCommand.Result.Succeeded;"

The completed C# code might look like this:

using System;
using Autodesk.Revit;

namespace DebugTest
{
  public class Command : IExternalCommand
  {
    public IExternalCommand.Result Execute( 
      ExternalCommandData commandData, 
      ref string message, 
      ElementSet elements )
    {
      return IExternalCommand.Result.Succeeded;
    }
  }
}

For VB, the equivalent steps are:

• Add a reference to RevitAPI.dll by opening the project, selecting the References tab, and clicking Add...
• Do not forget to set the 'Copy Local' flag to False. You do so by opening the properties of RevitAPI.dll. See The SDK Samples Solution for a more detailed explanation of this step.
• Remove the unneeded references to System.Data and System.Xml.
• Add a line at the top saying 'Imports Autodesk.Revit'. Note that Intellisense jumps in as soon as you have typed 'Autodesk.', so you almost never need to fully type out any identifier.
• Specify the IExternalCommand parent class for Command by adding a new line saying "Implements IExternalCommand" after "Public Class Command". Note here as well that Intellisense saves you from typing anything but the first few characters of the class name.
• Implement the Execute() method. In VB, you do not have the 'Implement Interface' option provided for C#, but you can go to the definition of IExternalCommand and copy the code from there.

The completed VB code might look like this:

Imports Autodesk.Revit

Public Class Command
    Implements IExternalCommand
    Function Execute( _
    ByVal commandData As ExternalCommandData, _
    ByRef message As String, _
    ByVal elements As ElementSet) _
    As Autodesk.Revit.IExternalCommand.Result _
    Implements Autodesk.Revit.IExternalCommand.Execute
        Return IExternalCommand.Result.Succeeded
    End Function
End Class

Both the C# and VB projects now compile and are ready to be loaded into Revit.

Remember that the goal of this exercise is to explain how to set up the debugger and a Revit project to be able to very efficiently run, test and debug the code, make changes to and recompile the source code, and restart Revit to get back to the same testing scenario again with a minimum of fuss.

As we already know, in order to load an add-in into Revit, we need to make it known to Revit first via an entry into Revit.ini, which is located in the same directory as Revit.exe. I add the following lines to Revit.ini:

[ExternalCommands]
ECCount=1

ECName1=Debug Test
ECDescription1=Sample add-in for Revit API blog
ECAssembly1=C:\tmp\revit\DebugTest\DebugTest\bin\Debug\DebugTest.dll
ECClassName1=DebugTest.Command

When finished editing Revit.ini, make sure to copy the entire file path to the clipboard by right clicking on the Revit.ini file tab in the Visual Studio editor. The reason is that this almost exactly provides the full path name that we require to specify Revit.exe as the debugging process in the next step.

Now we can set up Revit.exe as the debugging application. In C#, this is done by right clicking on the project in the solution explorer and selecting Properties in the context menu. In VB, we simply double click My Project. Select the Debug tab, select the radio button Start external program, and add the full path of Revit.exe. Since we already have the full path of Revit.ini in the clipboard, all we need to do is paste it in and change the three last characters to replace the file extension ini by exe.

Now we can start up Revit.exe simply by hitting the F5 key, or selecting the Visual Studio menu entry Debug > Start Debugging.

If you do not automatically pre-load a Revit model through the command line arguments, you will have to manually select a project before you can load and start testing, so obviously it is better to specify a start-up model. Once a model has been loaded and the full Revit menu is displayed, you can load the add-in.

Note that if you make sure that your current project appears first in the Revit Tools > External Tools menu, you can run it with a minimum of keystrokes by simply typing Alt + T, <Return>, <Return>.

Once you have tested your current issue and wish to recompile the updated code, the fastest way to exit Revit and get back to the compilation environment is to simply stop the debugger using the Visual Studio menu entry Debug > Stop Debugging or Shift + F5.

Finally, to pre-load a specific model when starting up Revit in the Visual Studio debugger, simply add the full path to the Revit RVT file in the Debug tab Start options, Command line arguments.

Once all of this is set up, and believe me it is faster to set up than to explain, you should be able to jump in and out of your full debugging and testing scenario within a matter of seconds.

Loading SDK Samples

The previous post discussed the use of the unified solution file SDKSamples2009.sln to manage, compile and search the entire collection of over hundred sample applications provided in the Revit SDK. In order to actually execute a sample for testing and debugging, it also needs to be loaded into Revit. The most direct way to achieve this is to edit Revit.ini to add an entry to the Revit Tools > External Tools menu. Another possibility is to use the Add-In Manager provided with the SDK. Both of these approaches are tedious or even impossible to execute manually if you really want to be able to look at any one of the samples at any time. Happily, a perfect solution to this problem is already included in the Revit SDK: RvtSamples.

RvtSamples is a Revit external application. That means that it can define a user interface within the Revit UI. The user interface can consist of menus and toolbars. Each menu entry or toolbar button can be linked to a Revit external command. What RvtSamples does is read a text file containing information about all the Revit SDK samples that are external commands and the menu structure that we would like these to be presented in and set up this structure in a hierarchical menu inside the Revit menu system.

By default, the text file is named RvtSamples.txt and lives either in the same directory as the RvtSamples assembly DLL, or one or two levels above it, based on the assumption the RvtSamples.dll is in a bin/Debug subdirectory of the RvtSamples source code directory.

RvtSamples.txt contains a combination of the information specifying the desired menu hierarchy and the information required to load and execute the sample code, which is more or less the same as the data required to specify an external command in Revit.ini, i.e. ECName, ECDescription, ECAssembly and ECClassName. In Revit.ini, these four are used to define the menu item text and the status bar description for the external command in the Revit user interface on one hand, and the command class assembly path and fully qualified class name including namespace prefix on the other. For RvtSamples, the description, assembly path and class name remain the same, and the menu item text is enhanced to include the full definition of the menu hierarchy. For example, here is the first entry from my RvtSamples.txt:

/RvtSamples/By Flavour/All/About Revit
Show the Revit product name, version and build number.
...\SDK\Samples\VersionChecking\CS\bin\Debug\VersionChecking.dll
Revit.SDK.Samples.VersionChecking.CS.Command

This is asking RvtSamples to construct a new top level menu RvtSamples in the Revit menu with a submenu 'By Flavour', another submenu 'All' within it, and, finally, a menu entry for the VersionChecking sample with the menu text 'About Revit'.

RvtSamples.txt comes pre-populated with entries all Revit SDK samples classified once by Revit flavour, i.e. Architecture, MEP and Structure, and secondly by Revit version, i.e. 8, 9, 2009 etc. Other classifications are conceivable and also useful. The problem is that with the over hundred samples provided, each new classification is going to generate over one hundred new menu entries in the Revit menu, and this will hit a built-in limit of about 500 pretty soon. Therefore, only two classifications have been implemented for the moment.

Looking again at the data entered into RvtSamples.txt, you may note that there is nothing at all limiting it to create one single top level menu, or to be used to manage only the Revit SDK samples. Actually, RvtSamples is a completely generic menu generator. You can easily add your own entries to RvtSamples.txt to manage other external commands as well. For instance, I append a pretty large file to RvtSamples.txt on my system to provide an additional menu giving access to all the ADN Revit training labs as well, as you can see here:

Once you have compiled RvtSamples, all you need to do to activate it, i.e. load it into Revit, is to add the following lines to Revit.ini:

[ExternalApplications]
EACount=1
EAClassName1=RvtSamples.Application
EAAssembly1=RvtSamples.dll

Obviously, if you already have defined a section for external applications in your Revit.ini files, you will add just the two appropriate lines for RvtSamples to that existing section. Once you have added the external application item into Revit.ini, RvtSamples will automatically create the specified additional menus and add menu items to the Revit menu for all samples listed in the text file every time Revit starts up.

Executive summary: RvtSamples is a generic Revit menu generator which reads a text file RvtSamples.txt listing all the Revit SDK samples categorised in various ways and creates a new top level hierarchical menu providing simultaneous classified access to all of them. It is not limited to making the samples available, the text file can contain arbitrary other menu entry definitions as well or instead of the Revit SDK sample ones defined in RvtSamples.txt.

• RvtSamples is an external application
• Defines entire menu hierarchy
• Generic menu generator
• Provides access to all Revit SDK samples
• Multiple categorisations
• Database driven
• Avoid hitting max. number of menu entries
• Minimal edits in Revit.ini
• Can be used for other external commands as well

The SDK Samples Solution SDKSamples2009.sln

As mentioned in the previous post, the Revit SDK samples include a powerful tool to help manage the over hundred individual samples provided. On one hand, we wish to compile all the samples easily in order to load and execute them inside of Revit for testing and debugging purposes. We also want a comfortable method to search for solutions to specific tasks. The unified solution file SDKSamples2009.sln addresses both these needs.

In order to compile the samples, every project included in the solution needs to reference the appropriate version of RevitAPI.dll. On a default installation of Revit Architecture, MEP, or Structure, the location of RevitAPI.dll is

C:\Program Files\Revit Architecture 2009\Program\RevitAPI.dll
C:\Program Files\Revit MEP 2009\Program\RevitAPI.dll
C:\Program Files\Revit Structure 2009\Program\RevitAPI.dll

They are all identical, more or less, although some of the API functionality is only available when running within the appropriate flavour of Revit.

If you installed Revit to the default location, the reference path to RevitAPI.dll stored in SDKSamples2009.sln will already be correct and no change is required. Otherwise, read on.

By the way, whenever you modify the reference to RevitAPI.dll in order to compile any Revit add-in, you need to make sure that the 'Copy Local' flag maintained by Visual Studio for that reference is set to False. You can see the current setting by right clicking on the reference and selecting its properties in the context menu. If this flag is set to True, Visual Studio will create a local copy of RevitAPI.dll when compiling the plug-in and use this copy when loading it. This confuses the debugger and Revit when running the add-in, as well as unnecessarily polluting your hard disk with copies of this multi-MB file.

To avoid having to reset this property when modifying an existing reference, simply do not delete the existing reference ... instead, add the new reference to the current assembly, and the old, existing data will be updated, so the new path will be stored, and at the same time the existing 'Copy Local' setting will be preserved.

Now, if you need to change the path to the references to RevitAPI.dll in all your hundred Revit SDK sample projects and want to do so by editing them manually one by one, you are in for a daunting task. Luckily, this can be automated.

The Visual Studio project file is actually an XML file, so all relevant project information is encoded in tags and attributes. The location of RevitAPI.dll on your system is encoded within the project file, inside a <HintPath> tag. You can easily use search and replace to redefine the location of RevitAPI.dll by modifying the hint path globally across hundreds of project files. One way to do this would be to use Visual Studio itself, either straight search and replace if you have one specific hint path value that you would like to modify, or by using regular expressions for more flexibility. I once wrote a command line utility to automate this task, the HintPath Batch Processor jhint.exe:

HintPath Batch Processor 1.0.0.1
Copyright (C) 2007 by Jeremy Tammik, Autodesk Inc.

usage: jhint [-?bhqrv] [-n new_hintpath] [-o old_hintpath_regex] filespecs

Options:
  -b  --backup          create backup files (no)
  -h  --help            display help message (no)
  -n  --newhintpath     specify new HintPath replacement (null)
  -o  --oldhintpath     specify old HintPath regular expression pattern (null)
  -q  --quiet           quiet mode (no)
  -r  --recursive       recursively traverse subdirectories (no)
  -v  --verbose         print verbose messages (no)

filespec may include both root directory and filename pattern, for example:
  C:\a\j\pro\jhint\test\*.csproj
  .\test\Project1.vbproj
  Project2.csproj

old HintPath regular expression search pattern examples:
  mgd.dll           matches all files containing the substring "mgd.dll"
  \\AutoCAD 2007\\  matches all files in some "AutoCAD 2007" subdirectory

If anyone is interested in hearing more about this tool, please let me know and I will happily present it in more detail.

Anyway, once the reference to RevitAPI.dll is set correctly for all the Revit SDK samples, you should be able to compile them all in one go by simply compiling the entire SDKSamples2009.sln solution.

This solution can also be used as a base for running and debugging into any one of the samples. In order to do so, we need to load the desired sample into Revit. This can be achieved by manually editing Revit.ini to add the sample to the Revit Tools > External Tools menu, but that would also be tedious if done manually one by one for each sample. In the next post, I plan to discuss a more efficient alternative.

To search for any solution to a specific problem, I find the functionality provided by Visual Studio > Edit > Find and Replace > Find in Files > Look in : Entire Solution very useful. For instance, if I am interested to create a wall, I might search globally for 'createwall'. This will turn up a number of hits. To be more precise, in my installation, 880 files are searched and 74 matching lines found in 18 files. Looking at these in more detail, I notice that some of them contain the string 'CreateWall'. So next, I narrow down the search to this exact string and match case. This reduces the number of hits to 10 in 5 files, and some of them are for the method CreateWall() in the Journaling sample. Looking at this method, I discover that the actual API method called to create a new wall is NewWall(). Looking for this exact string, I immediately determine which seven of the hundred SDK samples can be used to explore wall creation.