The Building Coder

CouchDB Implementation and GitHub Repository

I more or less completed the research for my cloud-based round-trip 2D Revit model editing project.

I'll describe some parts of that, and also address

• Three aspects of life and programming
• Room editor navigation
• Nested asynchronous database call-back functions
• Roomedit – my first GitHub project
• Debugging JavaScript with Firebug
• Screen snapshots on mobile devices
• Open source components used by Autodesk
• Retrieve slabs above specific walls

Lazy, Simple and Perfect

You will like the first slide of my upcoming tech summit presentation.

I start off with a couple of quotes on three fundamental aspects of software engineering and life in general:

• Lazy
• ... develop the three great virtues of a programmer: laziness, impatience, and hubris – Larry Wall
• Simple
• Simplicity is the ultimate sophistication – Leonardo da Vinci
• There is no greatness where there is no simplicity – Leo Tolstoy
• KISS
• Perfect
• Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away – Antoine de Saint-Exupéry

Basically, I demonstrate how easy it is to implement simple model navigation and 2D graphical editing using server-side scripting so that it works on all mobile devices.

So it is all about keeping it simple and easy.

Room Editor Navigation

The last instalment on this topic included a two-minute minimal demo recording illustrating its use and started describing the simplest aspect of the implementation, the server-side generated index.html home page that lists all models and prompts to select one of them.

From there, one navigates through the hierarchy of model > level > room > furniture and equipment. The latter finally reference the symbol objects that determine their geometry.

Now lets move on to the more interesting parts where the inter-related objects need to execute more complex queries to establish their relationships. I still have not covered the juicy part of rendering the SVG model, and the even juicier part of interacting with it, editing it, and updating the database with the changes made, either.

As said, the navigation logic is pretty trivial:

• Home page: list all models and prompt to select one of them.
• Model selected: list all levels in model and prompt to select one of them.
• Level selected: list all rooms on the level and prompt to select one of them.
• Room selected: display the room boundary and the furniture and equipment instances graphically and enable editing their location and rotation.

Basically, the entire implementation is all squeezed into one single overgrown index.html file.

Moving on from the home page to the second simplest part of it, we have selected a specific model and list all the levels it contains.

This navigation takes place by invoking the same index.html URL and adding a modelId parameter to it.

This parameter is picked up and used to query the database for all levels in the specified model.

To retrieve only the required ones, I use a CouchDB view mapping model id keys to level documents like this:

  map_model_to_level = {
    map: function (doc) {
      if( 'level' == doc.type ) {
        emit(doc.modelId, doc);
      }
    }
  };

I can specify a key to CouchDB when querying this view, i.e. make a REST API call with a parameter like this:

  .../roomedit/_design/roomedit/_views?key=12345

This will retrieve only those level documents from the database whose modelId value matches the given key.

Here is the part of index.html handling that interaction:

. . .

else if ( paramdict.hasOwnProperty( 'modelid' ) ) {

  //======================================================
  // display a menu of all levels in selected model
  //======================================================

  var mid = paramdict['modelid'];
  db.getDoc( mid,
    function(err,resp) {
      if (err) {
        return alert(JSON.stringify(err));
      }
      var modeldoc = resp;
      db.getView('roomedit',
        'map_model_to_level',
        { key: JSON.stringify(mid) },

        function (err, data) {
          if (err) {
            return alert(err);
          }
          var n = data.rows.length;
          for (var i = 0; i < n; ++i) {
            var doc = data.rows[i].value;
            if( doc.modelId != mid ) {
              alert( 'model ids differ: doc '
                + doc.modelId + ", url " + mid );
            }
            var s = url + '?levelid=' + doc._id;
            $('<li/>')
              .append($('<a>').attr('href',s).text(doc.name))
              .appendTo('#navigatorlist');
          }
          var p = $('<p/>').appendTo('#content');
          p.append( $('<a/>').text('Home').attr('href',url) );
          p.append( document.createTextNode( three_spaces ) );
          p.append( $('<a/>').text('Back').attr('href',url) );

          $('<p/>')
            .text( 'Please select a level in the list below.' )
            .appendTo('#content');

          var table = $('<table/>').appendTo('#content');
          table.append( '<tr><td>' + 'Model:'
            + '</td><td>' + modeldoc.name + '</td></tr>' );

          var prompt = n.toString() + ' level'
            + pluralSuffix( n ) + ' in model ';

          var p = $('<p/>').text( prompt ).appendTo('#content');
          p.append( $('<i/>').text( modeldoc.name ) );
          p.append( document.createTextNode( dotOrColon( n ) ) );
        }
      );
    }
  );
}

As I already mentioned, this is populating an super simple HTML skeleton containing the following nodes:

  <h1>Room Editor</h1>

  <div id="content"></div>

  <ul id="navigatorlist"></ul>

Here is the result in a model named 'Roombook' containing a single level 'Fondations':

Nested Asynchronous Database Call-back Functions

One challenge for me in the room editor CouchDB implementation was understanding how the asynchronous database call-back functions work, and how I can nest them to retrieve all the results I need.

In the case above, the situation is still very simple: I need to perform two database queries:

• Query a specific document, the model, using the db.getDoc function.
• Query all the levels it contains, which are returned by the map_model_to_level view with the model id key, using the getView function.

Both the getDoc and getView functions take an asynchronous call-back function as an argument.

I found out the hard way that I can nest these within each other to ensure that I have all up-to-date results before I display my page.

This gets a bit more hairy as the number of queries and thus the number of nested functions grows...

Roomedit – My First GitHub Project

Anyway, I have it all happily running now, and published the roomedit CouchDB application implementing this as my first ever GitHub project.

Debugging JavaScript with FireFox FireBug

Everybody makes errors. In my HTML and JavaScript code, these sometimes caused my index.html not to display anything at all.

Often this was due to some trivial JavaScript typo that would have been really hard to chase down.

Enter Firebug, thank God.

This is a great tool that I have started to rely on greatly to help me out of tight corners.

The Firebug debugging console is integrated in FireFox and includes support for examining and debugging all kinds of aspects of a web page.

You can open the Firebug console on any web page through Tools > Web Developer > Firebug > Open Firebug. That displays a new panel at the bottom of the browser with tabs for

• Console
• HTML
• CSS
• Script
• DOM
• Net
• Cookies

I use Console and Script, mostly.

The former displays the location of a JavaScript error and jumps to it when loading the file. It also lists the URLs visited and stuff like that, which is very useful for analysing the REST API calls being made.

The script tab provides a JavaScript debugger allowing you to set breakpoints and analyse variable values etc.

There are lots of tutorials and documentation available on this feature, such as these ones on Firebug and JavaScript debugging, so I will not trouble you any further with my description.

To tell the truth, though, I never looked at any of them.

The thing just worked for me, is incredibly valuable, and I am grateful.

Screen Snapshots on Mobile Devices

Here is a quick guide how to create a screen snapshot on various types of mobile devices:

• iPhone – Press the Sleep/Wake and Home buttons together; the screen will fade temporarily, signalling that the screen shot was saved in your Camera Roll:
  
• Android – Press the Power and Home buttons together, or hold down the Lock/Power and Volume Down buttons together:
  
• Windows 8 – Press the Lock/Power and Home/Windows buttons together:
  

Open Source Components used by Autodesk

A colleague pointed out this open source repository containing all open source components used in AutoCAD, Map 3D and other Autodesk products.

I was actually surprised how short the list is. Anyway, it might be useful to know about.

Retrieve Slabs Above Certain Walls

Let's wrap this up with a standard Revit API question:

Question: I want to determine the slab above the walls of a particular room.

How can retrieve those using the Revit API, please?

Answer: As so often in Revit, there are a number of different possibilities, and it depends in part upon how the building has been modelled.

In a structural model, you may be able to query the analytical support data. I have no idea whether this information is included there, but my naive assumption would be that this should be possible.

Much more generally, you can analyse and query the geometry in a number of different ways.

The two possibilities that immediately spring to mind are:

• Use the ray casting functionality provided by the Document FindReferencesWithContextByDirection method and the ReferenceIntersector wrapper class.
• Use the geometric proximity functionality provided by some element filters, e.g.

The discussion on determining the columns supporting a beam demonstrates several different variations of the latter. Earlier blog posts include examples of the former as well.

Response: I was able to use the functionality for finding the supporting columns for beams from your link to solve my issue as well.

In my case, beam.GetGeneratingElementIds returns the desired supported floors.

I also tested using an ElementIntersectsSolidFilter to retrieve all walls that intersect the floor using the floor solid geometry object:

  Solid solid = null;
  ElementFilter slabIntersectFilter
    = new ElementIntersectsSolidFilter( solid );
 
  FilteredElementCollector walls
    = new FilteredElementCollector( doc )
      .WhereElementIsNotElementType()
      .OfClass( typeof( Wall ) )
      .WherePasses( slabIntersectFilter );

This also solved my issue. It can be the alternative when beams are not there.

Room and Furniture Loops Using Symbols

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I now implemented the first of the next steps mentioned at the end:

• Separation of symbol and instance data in my add-in and database structure: currently, the furniture loops are placed absolutely, and multiple instances of a symbol duplicate the same loop over and over again at different locations. I will rewrite this to separate the furniture loop definition, defined by the family symbol, and its placement, defined by the instance. This needs to be done anyway to enable editing the placement data through the editor interaction on the mobile device.

The first implementation just uploaded the room and furniture instance 2D boundary polygon loops, absolutely placed.

Besides converting that to defining and reusing symbols, I also added support for exporting the model and level data to the cloud.

I discuss the implementation of that here now:

• Database structure
• Database upload
• Integer based 2D placement
• Populating symbols and instances
• Retrieving the boundary loops
• GeoSnoop loop display
• Caveats
• Download
• Next steps

Database Structure

I enhanced the database classes to include a new class DbSymbol. It defines the family symbol loop, which is reused by the family instances.

The DbFurniture class no longer has its own individual loop data. Instead, it has a reference to a symbol and placement data defining its 2D translation and rotation.

All the database classes are derived from the DbObj base class:

• DbObj
• Type
• Description
• Name

Some of the derived classes have no additional properties of their own at all. The data structure is this as simple as this:

• DbModel
• DbLevel
• ModelId
• DbRoom
• LevelId
• Loops
• ViewBox
• DbSymbol
• Loop
• DbFurniture
• RoomId
• SymbolId
• Transform

The source code does nothing but exactly reproduce this structure. Here is the complete implementation of these classes:

  /// <summary>
  /// Base class for all Jeremy Room Editor classes.
  /// </summary>
  class DbObj : CouchDocument
  {
    protected DbObj()
    {
      Type = "obj";
    }
    public string Type { get; protected set; }
    public string Description { get; set; }
    public string Name { get; set; }
  }
 
  /// <summary>
  /// Current model, i.e. Revit project.
  /// </summary>
  class DbModel : DbObj
  {
    public DbModel()
    {
      Type = "model";
    }
  }
 
  /// <summary>
  /// Level.
  /// </summary>
  class DbLevel : DbObj
  {
    public DbLevel()
    {
      Type = "level";
    }
    public string ModelId { get; set; }
  }
 
  /// <summary>
  /// Room
  /// </summary>
  class DbRoom : DbObj
  {
    public DbRoom()
    {
      Type = "room";
    }
    public string LevelId { get; set; }
    public string Loops { get; set; }
    public string ViewBox { get; set; }
  }
 
  /// <summary>
  /// Family symbol, i.e. element type defining 
  /// the geometry, i.e. the 2D boundary loop.
  /// </summary>
  class DbSymbol : DbObj
  {
    public DbSymbol()
    {
      Type = "symbol";
    }
    public string Loop { get; set; }
  }
 
  /// <summary>
  /// Family instance, defining placement, i.e.
  /// transform, i.e. translation and rotation,
  /// and referring to the symbol geometry.
  /// </summary>
  class DbFurniture : DbObj
  {
    public DbFurniture()
    {
      Type = "furniture";
    }
    public string RoomId { get; set; }
    public string SymbolId { get; set; }
    public string Transform { get; set; }
  }

Database Upload

The database upload has not changed very much from the previous version, except that the model, level and symbol data is now added, and the furniture and equipment instances store their symbol reference and transformation:

/// <summary>
/// Upload model, level, room and furniture data 
/// to an IrisCouch hosted CouchDB data repository.
/// </summary>
static public void DbUploadRoom(
  Room room,
  List<Element> furniture,
  JtLoops roomLoops,
  Dictionary<string, JtLoop> furnitureLoops,
  List<JtPlacement2dInt> furnitureInstances )
{
  CouchClient client = new CouchClient(
    _web_url,
    5984 );
 
  CouchDatabase db = client.GetDatabase(
    _database_name, true );
 
  Document doc = room.Document;
 
  Element projectInfo
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ProjectInfo ) )
      .FirstElement();
 
  string uid = projectInfo.UniqueId;
 
  DbModel dbModel;
 
  if( db.DocumentExists( uid ) )
  {
    dbModel = db.GetDocument<DbModel>( uid );
 
    Debug.Assert(
      dbModel.Id.Equals( projectInfo.UniqueId ),
      "expected equal ids" );
 
    dbModel.Description = Util.ElementDescription(
      projectInfo );
 
    dbModel.Name = projectInfo.Document.Title;
 
    dbModel = db.UpdateDocument<DbModel>(
      dbModel );
  }
  else
  {
    dbModel = new DbModel();
 
    dbModel.Id = uid;
    dbModel.Description = Util.ElementDescription(
      projectInfo );
 
    dbModel.Name = projectInfo.Name;
    dbModel = db.CreateDocument<DbModel>( dbModel );
  }
 
  Level level = room.Level;
 
  uid = level.UniqueId;
 
  DbLevel dbLevel;
 
  if( db.DocumentExists( uid ) )
  {
    dbLevel = db.GetDocument<DbLevel>( uid );
 
    Debug.Assert(
      dbLevel.Id.Equals( level.UniqueId ),
      "expected equal ids" );
 
    dbLevel.Description = Util.ElementDescription(
      level );
 
    dbLevel.Name = level.Name;
    dbLevel.ModelId = projectInfo.UniqueId;
 
    dbLevel = db.UpdateDocument<DbLevel>(
      dbLevel );
  }
  else
  {
    dbLevel = new DbLevel();
 
    dbLevel.Id = uid;
    dbLevel.Description = Util.ElementDescription(
      level );
 
    dbLevel.Name = level.Name;
    dbLevel.ModelId = projectInfo.UniqueId;
 
    dbLevel = db.CreateDocument<DbLevel>(
      dbLevel );
  }
 
  uid = room.UniqueId;
 
  DbRoom dbRoom;
 
  if( db.DocumentExists( uid ) )
  {
    dbRoom = db.GetDocument<DbRoom>( uid );
 
    Debug.Assert(
      dbRoom.Id.Equals( room.UniqueId ),
      "expected equal ids" );
 
    dbRoom.Description = Util.ElementDescription(
      room );
 
    dbRoom.Name = room.Name;
    dbRoom.LevelId = level.UniqueId;
    dbRoom.Loops = roomLoops.SvgPath;
    dbRoom.ViewBox = roomLoops.BoundingBox.SvgViewBox;
 
    dbRoom = db.UpdateDocument<DbRoom>( dbRoom );
  }
  else
  {
    dbRoom = new DbRoom();
 
    dbRoom.Id = uid;
    dbRoom.Description = Util.ElementDescription(
      room );
 
    dbRoom.Name = room.Name;
    dbRoom.LevelId = level.UniqueId;
    dbRoom.Loops = roomLoops.SvgPath;
    dbRoom.ViewBox = roomLoops.BoundingBox.SvgViewBox;
 
    dbRoom = db.CreateDocument<DbRoom>( dbRoom );
  }
 
  foreach( KeyValuePair<string, JtLoop> p in furnitureLoops )
  {
    uid = p.Key;
    Element e = doc.GetElement( uid );
    if( db.DocumentExists( uid ) )
    {
      DbSymbol symbol = db.GetDocument<DbSymbol>(
        uid );
 
      symbol.Description = Util.ElementDescription( e );
      symbol.Name = e.Name;
      symbol.Loop = p.Value.SvgPath;
 
      symbol = db.UpdateDocument<DbSymbol>( symbol );
    }
    else
    {
      DbSymbol symbol = new DbSymbol();
      symbol.Id = uid;
      symbol.Description = Util.ElementDescription( e );
      symbol.Name = e.Name;
      symbol.Loop = p.Value.SvgPath;
 
      symbol = db.CreateDocument<DbSymbol>( symbol );
    }
  }
 
  foreach( FamilyInstance f in furniture )
  {
    uid = f.UniqueId;
    if( db.DocumentExists( uid ) )
    {
      DbFurniture dbf = db.GetDocument<DbFurniture>(
        uid );
 
      dbf.Description = Util.ElementDescription( f );
      dbf.Name = f.Name;
      dbf.RoomId = room.UniqueId;
      dbf.SymbolId = f.Symbol.UniqueId;
      dbf.Transform = new JtPlacement2dInt( f )
        .SvgTransform;
 
      dbf = db.UpdateDocument<DbFurniture>( dbf );
    }
    else
    {
      DbFurniture dbf = new DbFurniture();
      dbf.Id = uid;
      dbf.Description = Util.ElementDescription( f );
      dbf.Name = f.Name;
      dbf.RoomId = room.UniqueId;
      dbf.SymbolId = f.Symbol.UniqueId;
      dbf.Transform = new JtPlacement2dInt( f )
        .SvgTransform;
 
      dbf = db.CreateDocument<DbFurniture>( dbf );
    }
  }
}

Integer Based 2D Placement

I implemented the following simple class to manage the 2D placement.

It is based on the 2D point class, storing the coordinate data in integers, for various reasons:

• Revit precision is no smaller than one sixteenth of an inch, ca. 1.2 mm.
• The data is stored in the cloud and rendered on a mobile device: the use of integers
• eliminates rounding issues,
• lowers the data volume,
• enhances performance,
• simplifies storage,
• improves human reading and understanding.

Since I am already using millimetres for the length measurement, I find it fitting to store the rotation in degrees. The SVG rendering expects degrees as input, anyway.

Here is the class implementation:

/// <summary>
/// A 2D integer-based transformation, 
/// i.e. translation and rotation.
/// </summary>
class JtPlacement2dInt
{
  /// <summary>
  /// Translation.
  /// </summary>
  public Point2dInt Translation { get; set; }
 
  /// <summary>
  /// Rotation in degrees.
  /// </summary>
  public int Rotation { get; set; }
 
  /// <summary>
  /// The family symbol UniqueId.
  /// </summary>
  public string SymbolId { get; set; }
 
  public JtPlacement2dInt( FamilyInstance fi )
  {
    LocationPoint lp = fi.Location as LocationPoint;
 
    Debug.Assert( null != lp,
      "expected valid family instanace location point" );
 
    Translation = new Point2dInt( lp.Point );
 
    Rotation = (int) (
      ( ( 180 * lp.Rotation ) + 0.5 ) / Math.PI );
 
    SymbolId = fi.Symbol.UniqueId;
  }
 
  /// <summary>
  /// Return an SVG transform,
  /// either for native SVG or Raphael.
  /// </summary>
  public string SvgTransform
  {
    get
    {
      return string.Format(
        "R{2}T{0},{1}",
        //"translate({0},{1}) rotate({2})",
        Translation.X, Translation.Y, Rotation );
    }
  }
}

The placement is instantiated from a family instance, and returns a suitably formatted SVG transformation string, either for native SVG or the Raphaël JavaScript SVG library.

Populating Symbols and Instances

To populate the symbol and instance data, I loop over all the instances exactly like I did previously.

Now, instead of exporting the family instance boundary loop in situ, I transform it back to the symbol definition coordinate system instead, and save that in a dictionary mapping the family symbol UniqueId to its boundary loop.

The family instance exports a reference to that symbol and its placement data:

  List<Element> furniture
    = GetFurniture( room );
 
  // Map symbol UniqueId to symbol loop
 
  Dictionary<string, JtLoop> furnitureLoops
    = new Dictionary<string, JtLoop>();
 
  // List of instances referring to symbols
 
  List<JtPlacement2dInt> furnitureInstances
    = new List<JtPlacement2dInt>(
      furniture.Count );
 
  int nFailures;
 
  foreach( FamilyInstance f in furniture )
  {
    FamilySymbol s = f.Symbol;
 
    string uid = s.UniqueId;
 
    if( !furnitureLoops.ContainsKey( uid ) )
    {
      nFailures = 0;
 
      JtLoops loops = GetPlanViewBoundaryLoops(
        f, ref nFailures );
 
      if( 0 < nFailures )
      {
        Debug.Print( "{0}: {1} extrusion analyser failure{2}",
          Util.ElementDescription( f ), nFailures,
          Util.PluralSuffix( nFailures ) );
      }
      ListLoops( f, loops );
 
      if( 0 < loops.Count )
      {
        // Assume first loop is outer one
 
        furnitureLoops.Add( uid, loops[0] );
      }
    }
    furnitureInstances.Add(
      new JtPlacement2dInt( f ) );
  }

Retrieving the Boundary Loops

The boundary loop retrieval has not changed very much, although the following significant enhancements were made:

• Store the symbol loop in the original symbol definition coordinate system.
• Store the instance transformation data.
• Manage the dictionary of symbols and the instances referencing them.
• Save intermediate tessellated curve points, not just start and end point. This functionality can be toggled on and off by setting the Boolean _tessellate_curves switch.

The implementation is separated into two methods:

• AddLoops: add the plan view boundary loops from a given solid to the list of loops.
• GetPlanViewBoundaryLoops: Retrieve the plan view boundary loops from all solids of given element united together. If the element is a family instance, transform its loops from the instance placement coordinate system back to the symbol definition one.

Here is the implementation:

/// <summary>
/// Add all plan view boundary loops from 
/// given solid to the list of loops.
/// The creation application argument is used to
/// reverse the extrusion analyser output curves
/// in case they are badly oriented.
/// </summary>
/// <returns>Number of loops added</returns>
int AddLoops(
  Autodesk.Revit.Creation.Application creapp,
  JtLoops loops,
  GeometryObject obj,
  ref int nExtrusionAnalysisFailures )
{
  int nAdded = 0;
 
  Solid solid = obj as Solid;
 
  if( null != solid
    && 0 < solid.Faces.Size )
  {
    Plane plane = new Plane( XYZ.BasisX,
      XYZ.BasisY, XYZ.Zero );
 
    ExtrusionAnalyzer extrusionAnalyzer = null;
 
    try
    {
      extrusionAnalyzer = ExtrusionAnalyzer.Create(
        solid, plane, XYZ.BasisZ );
    }
    catch( Autodesk.Revit.Exceptions
      .InvalidOperationException )
    {
      ++nExtrusionAnalysisFailures;
      return nAdded;
    }
 
    Face face = extrusionAnalyzer
      .GetExtrusionBase();
 
    foreach( EdgeArray a in face.EdgeLoops )
    {
      int nEdges = a.Size;
 
      List<Curve> curves
        = new List<Curve>( nEdges );
 
      XYZ p0 = null; // loop start point
      XYZ p; // edge start point
      XYZ q = null; // edge end point
 
      foreach( Edge e in a )
      {
        // This returns the curves already
        // correctly oriented:
 
        curve = e.AsCurveFollowingFace(
          face );
 
        if( _debug_output )
        {
          p = curve.get_EndPoint( 0 );
          q = curve.get_EndPoint( 1 );
          Debug.Print( "{0} --> {1} following face",
            Util.PointString( p ),
            Util.PointString( q ) );
        }
 
        curves.Add( curve );
      }
 
      q = null;
 
      JtLoop loop = new JtLoop( nEdges );
 
      foreach( Curve curve in curves )
      {
        p = curve.get_EndPoint( 0 );
 
        Debug.Assert( null == q
          || q.IsAlmostEqualTo( p, 1e-05 ),
          string.Format(
            "expected last endpoint to equal current start point, not distance {0}",
            (null == q ? 0 : p.DistanceTo( q ))  ) );
 
        q = curve.get_EndPoint( 1 );
 
        if( _debug_output )
        {
          Debug.Print( "{0} --> {1}",
            Util.PointString( p ),
            Util.PointString( q ) );
        }
 
        if( null == p0 )
        {
          p0 = p; // save loop start point
        }
 
        int n = -1;
 
        if( _tessellate_curves
          && _min_tessellation_curve_length_in_feet
            < q.DistanceTo( p ) )
        {
          IList<XYZ> pts = curve.Tessellate();
          n = pts.Count;
 
          Debug.Assert( 1 < n, "expected at least two points" );
          Debug.Assert( p.IsAlmostEqualTo( pts[0] ), "expected tessellation start equal curve start point" );
          Debug.Assert( q.IsAlmostEqualTo( pts[n-1] ), "expected tessellation end equal curve end point" );
 
          if( 2 == n )
          {
            n = -1; // this is a straight line
          }
          else
          {
            --n; // skip last point
 
            for( int i = 0; i < n; ++i )
            {
              loop.Add( new Point2dInt( pts[i] ) );
            }
          }
        }
 
        // If tessellation is disabled,
        // or curve is too short to tessellate,
        // or has only two tessellation points,
        // just add the start point:
 
        if( -1 == n )
        {
          loop.Add( new Point2dInt( p ) );
        }
      }
      Debug.Assert( q.IsAlmostEqualTo( p0, 1e-05 ),
        string.Format(
          "expected last endpoint to equal current start point, not distance {0}",
          p0.DistanceTo( q ) ) );
 
      loops.Add( loop );
 
      ++nAdded;
    }
  }
  return nAdded;
}

/// <summary>
/// Retrieve all plan view boundary loops from 
/// all solids of given element united together.
/// If the element is a family instance, transform
/// its loops from the instance placement 
/// coordinate system back to the symbol 
/// definition one.
/// </summary>
JtLoops GetPlanViewBoundaryLoops(
  Element e,
  ref int nFailures )
{
  Autodesk.Revit.Creation.Application creapp
    = e.Document.Application.Create;
 
  JtLoops loops = new JtLoops( 1 );
 
  Options opt = new Options();
 
  GeometryElement geo = e.get_Geometry( opt );
 
  if( null != geo )
  {
    Document doc = e.Document;
 
    if( e is FamilyInstance )
    {
      // Retrieve family instance geometry 
      // transformed back to symbol definition
      // coordinate space by inverting the 
      // family instance placement transformation
 
      LocationPoint lp = e.Location
        as LocationPoint;
 
      Transform t = Transform.get_Translation(
        -lp.Point );
 
      Transform r = Transform.get_Rotation(
        lp.Point, XYZ.BasisZ, -lp.Rotation );
 
      geo = geo.GetTransformed( t * r );
    }
 
    Solid union = null;
 
    Plane plane = new Plane( XYZ.BasisX,
      XYZ.BasisY, XYZ.Zero );
 
    foreach( GeometryObject obj in geo )
    {
      Solid solid = obj as Solid;
 
      if( null != solid
        && 0 < solid.Faces.Size )
      {
        // Some solids, e.g. in the standard 
        // content 'Furniture Chair - Office' 
        // cause an extrusion analyser failure,
        // so skip adding those.
 
        try
        {
          ExtrusionAnalyzer extrusionAnalyzer
            = ExtrusionAnalyzer.Create(
              solid, plane, XYZ.BasisZ );
        }
        catch( Autodesk.Revit.Exceptions
          .InvalidOperationException )
        {
          solid = null;
          ++nFailures;
        }
 
        if( null != solid )
        {
          if( null == union )
          {
            union = solid;
          }
          else
          {
            union = BooleanOperationsUtils
              .ExecuteBooleanOperation( union, solid,
                BooleanOperationsType.Union );
          }
        }
      }
    }
    AddLoops( creapp, loops, union, ref nFailures );
  }
  return loops;
}

GeoSnoop Loop Display

I obviously had to update my GeoSnoop display to take the symbol loop dictionary lookup into account.

I invoke it passing in the room loops, symbol loops, and instance placements:

  GeoSnoop.DisplayLoops( revit_window,
    "Room and furniture", roomLoops,
    furnitureLoops, furnitureInstances );

The new implementation displays the instances at their respective location by transforming the referenced symbol geometry accordingly.

I make use of two transformations:

• Matrix transform: Transform from native loop coordinate system to target display coordinates.
• Matrix placement: Additional transformation from symbol definition to instance location for placing an individual instance.

It also takes the aspect ratio of the room to display into account and adjusts the window height to fit, based on the room bounding box aspect ratio:

/// <summary>
/// Display a collection of loops in a .NET form.
/// </summary>
class GeoSnoop
{
  /// <summary>
  /// Pen size.
  /// </summary>
  const int _pen_size = 1;
 
  /// <summary>
  /// Pen colour.
  /// </summary>
  static Color _pen_color = Color.Black;
 
  /// <summary>
  /// Margin around graphics.
  /// </summary>
  const int _margin = 10;
 
  /// <summary>
  /// Draw loops on graphics with the specified
  /// transform and graphics attributes.
  /// </summary>
  static void DrawLoopsOnGraphics(
    Graphics graphics,
    List<Point[]> loops,
    Matrix transform )
  {
    Pen pen = new Pen( _pen_color, _pen_size );
 
    foreach( Point[] loop in loops )
    {
      GraphicsPath path = new GraphicsPath();
 
      transform.TransformPoints( loop );
 
      path.AddLines( loop );
 
      graphics.DrawPath( pen, path );
    }
  }
 
  /// <summary>
  /// Display loops in a temporary form generated
  /// on the fly.
  /// </summary>
  /// <param name="owner">Owner window</param>
  /// <param name="caption">Form caption</param>
  /// <param name="loops">Boundary loops</param>
  public static void DisplayLoops(
    IWin32Window owner,
    string caption,
    JtLoops roomLoops,
    Dictionary<string, JtLoop> furnitureLoops,
    List<JtPlacement2dInt> furnitureInstances )
  {
    JtBoundingBox2dInt bb = roomLoops.BoundingBox;
 
    // Adjust target rectangle height to the 
    // displayee loop height.
 
    int width = 400;
    int height = (int) (width * bb.AspectRatio + 0.5);
 
    // Specify transformation target rectangle 
    // including a margin.
 
    int bottom = height - (_margin + _margin);
 
    Point[] parallelogramPoints = new Point[] {
      new Point( _margin, bottom ), // upper left
      new Point( width - _margin, bottom ), // upper right
      new Point( _margin, _margin ) // lower left
    };
 
    // Transform from native loop coordinate system
    // to target display coordinates.
 
    Matrix transform = new Matrix(
      bb.Rectangle, parallelogramPoints );
 
    Bitmap bmp = new Bitmap( width, height );
    Graphics graphics = Graphics.FromImage( bmp );
 
    graphics.Clear( System.Drawing.Color.White );
 
    DrawLoopsOnGraphics( graphics,
      roomLoops.GetGraphicsPathLines(), transform );
 
    List<Point[]> loops = new List<Point[]>( 1 );
    loops.Add( new Point[] { } );
 
    foreach( JtPlacement2dInt i in furnitureInstances )
    {
      Point2dInt v = i.Translation;
      Matrix placement = new Matrix();
      placement.Rotate(i.Rotation);
      placement.Translate(v.X, v.Y, MatrixOrder.Append);
      placement.Multiply( transform, MatrixOrder.Append );
      loops[0] = furnitureLoops[i.SymbolId]
        .GetGraphicsPathLines();
 
      DrawLoopsOnGraphics( graphics, loops, placement );
    }
 
    Form form = new Form();
    form.Text = caption;
    form.Size = new Size( width + 7, height + 13 );
    form.FormBorderStyle = FormBorderStyle
      .FixedToolWindow;
 
    PictureBox pb = new PictureBox();
    pb.Location = new System.Drawing.Point( 0, 0 );
    pb.Dock = System.Windows.Forms.DockStyle.Fill;
    pb.Size = bmp.Size;
    pb.Parent = form;
    pb.Image = bmp;
 
    form.ShowDialog( owner );
  }
}

Still very short and sweet, isn't it?

Here is the result of displaying a room from the advanced sample project provided with Revit:

Those eight straight lines in the corners are columns. I should eliminate those. We don't want to move those around indiscriminately on a mobile device anyway, or the whole house might come crashing down around us.

Caveats

Rudolf Honke wrote in a reaction to my plan described last time:

You say that you want to avoid redundant geometry data in your cloud project:

As you know, it is possible to modify the geometry of an individual family instance by cutting voids off it. The geometry of such an instance differs from other ones.

As far as I remember, modifying instance geometry this way has been possible since Revit 2012 or so; the API 2013 says:

"FamilyInstance.GetOriginalGeometry: Returns the original geometry of the instance, before the instance is modified by joins, cuts, coping, extensions, or other post-processing."

Thus, there are at least three groups of elements to be handled:

• Individual elements, such as walls – have individual geometry, cannot be reused
• Family instances which have not been modified – can be instantiated, geometry is reusable
• Family instances which are post-processed, resulting in individual geometry – not reusable

In this case, I am only handling furniture and equipment instances that I do not expect to be modified.

After all, the plan is to move them around in the room, so they have to be free of constraints for it to work.

Still, these considerations obviously have to be taken into account for other applications.

Download

To wrap this up for the moment, here is GeoSnoopSymbols.zip containing the complete source code, Visual Studio solution and add-in manifest of the current state of this external command.

Next Steps

My next steps will be:

• Migrate this add-in from Revit 2013 to 2014.
• Implement server-side generated SVG code to display the room and furniture plan in CouchDB using Kanso.
• Implement editing of SVG on the mobile device and reflect changes back to CouchDB (I know how now).
• Implement Idling event handler and polling of CouchDB in the desktop add-in to reflect the changes back to the BIM in real-time.
• Implement an external application wrapper for the add-in providing four commands:
• Upload to cloud
• Refresh from cloud
• Subscribe to cloud
• Unsubscribe from cloud

I know exactly how to address all these points now, no exceptions left. Yay!

I look forward to hearing your comments and suggestions.

Migrating a Built-in Category and Other Things

Here is a category related issue that appeared when migrating from the Revit 2013 to the Revit 2014 API, plus a several other typical simple little Revit API questions from the last day or two:

• Migrating the room separation lines built-in category
• Storage of RGB colour values for materials
• Updating a DXF link
• Retrieving truss family elements
• Retrieving stair stringer data
• Storing custom data

Migrating the Room Separation Lines Built-in Category

Question: I get the following error while migrating my C# code from Revit 2013 to Revit 2014:

• 'Autodesk.Revit.DB.BuiltInCategory' does not contain a definition for 'OST_AreaSeparationLines'

It is caused by the following line of code:

  ICollection<Element> collection
    = collector.OfCategory(
        BuiltInCategory.OST_AreaSeparationLines )
      .ToElements();

Do you have any solution to suggest?

Answer: The easiest way to fix this kind of issue is to look at an element that has this category using RevitLookup in Revit 2013, and then load the same model and see what category it has in Revit 2014.

Response: That worked!

It seems to be called OST_RoomSeparationLines now.

Problem solved.

Storage of RGB Colour Values for Materials

Question: I looked at a material element 'Color' parameter value today. This parameter values comes back as an integer.

It appears to me to have the red and blue values reversed.

When looking at the 'Site – Earth' material in the rac_advanced_sample_project included with Revit, the Color property on the material class returns material.Color.Red=97, material.Color.Green=75 and material.Color.Blue=62, which is also what the Revit GUI shows in 'Manage Materials'. I checked on an online colour generator web site and it looks the same as in the Revit GUI, a dirty brown colour.

However, the integer number that comes back from the 'Color' parameter on the material element is 4082529, which when converted to RGB values using online converters, comes back as Red=62, Green=75 and Blue=97, which is a bluish colour. The Red and Blue values appear to be reversed.

I would have expected the integer 6376254 to be returned for this colour instead.

Can you explain this, please?

Answer: Yes, easily.

This is actually working as expected.

Revit uses the Windows convention of storing colours as an RGB COLORREF value in a DWORD (32 bit integer) that specifies "The low-order byte contains a value for the relative intensity of red; the second byte contains a value for green; and the third byte contains a value for blue".

In other words it is (A)BGR and not (A)RGB.

This corresponds to the value of the integer returned from a Color parameter.

Updating a DXF Link

Question: I have created a DXF link DXF using the following code:

  DWGImportOptions opt = new DWGImportOptions();
  ElementId linkId;
 
  if( doc.Link( "C:\\tmp\\test.dxf",
    opt, doc.ActiveView, out linkId ) )
  {
    Element e = doc.GetElement( linkId );
    ImportInstance i = e as ImportInstance;
  }

Later, the DXF is modified by an external application.

Is it possible to programmatically force Revit to reload the link?

I think I could also delete the ImportInstance and create a new one, but I don't how to get the proper DWGImportOptions and DXF file path from the existing ImportInstance.

Answer: Yes, this can easily be achieved. You can use the RevitLinkType.Unload method to unload it first, and then call RevitLinkType.Reload to reload the updated DXF file.

The imported DXF file has the type of CADLinkType. Just as you say, you could also delete the link and import it again.

You can find the imported DXF ImportInstance's original path by calling the ExternalFileReference.GetPath method, and the ExternalFileUtils.GetExternalRefernce method will return the ImportInstance's ExternalFileReference object.

Retrieving Truss Family Elements

Question: How can I retrieve a truss element family instance?

Answer: This is a very basic question, answered many times over in the Revit API getting started material.

I recommend that you take a look at that material, work through the 'My First Revit Plugin' and DevTV tutorials, install the Revit SDK, RevitLookup, RvtSamples, and then answer that question for yourself.

I'll just give you one little additional hint to help get you started:

Every access to a Revit database element is achieved using a filtered element collector.

To retrieve all truss family instances, you could use something like this:

  FilteredElementCollector collector
    = new FilteredElementCollector( doc )
      .OfClass( typeof( FamilyInstance ) )
      .OfCategory( BuiltInCategory.OST_Truss );
 
  foreach( Element e in collector )
  {
    // e is a truss family instance
  }

Retrieval of Stair Stringer Data

Question: I want to access the values of the stair stringer height and thickness properties on a stair element. How can I achieve this, please?

I tried using the built-in parameters STAIRS_ATTR_STRINGER_THICKNESS and STAIRS_ATTR_STRINGER_HEIGTH, but the value being returned is null. I am also unable to get the family symbol of the stair element.

Answer: The two parameters that you are trying to access are stored on the stair type, not the stair itself.

The stair type is represented by the ElementType class, not FamilySymbol.

You can access the stair type and the two desired paramaters like this:

  Document doc = stair.Document;
 
  ElementId id = stair.GetTypeId();
 
  ElementType type = doc.get_Element( id )
    as ElementType;
 
  Parameter pThick = type.get_Parameter(
    BuiltInParameter.STAIRS_ATTR_STRINGER_THICKNESS );
 
  Parameter pHeight = type.get_Parameter(
    BuiltInParameter.STAIRS_ATTR_STRINGER_HEIGHT );
 
  double thick = pThick.AsDouble();
  double height = pHeight.AsDouble();

Storing Custom Data

Response: I need more than just the path. I would like to retrieve other DWGImportOptions parameters as well. Is it possible to get them somehow?

Answer: I don't think there is any way to retrieve all the ImportInstance's DWGImportOptions.

Since the DXF file was imported by your own code, you can easily work around that gap by storing the DWGImportOptions property values of interest in the ImportInstance object.

You can use extensible storage (wiki, category) to store custom data on Revit elements.

When you use this, you can later read back the settings from the extensible storage data.

Filter for Family Instances in a Room

I wish you a Good Friday.

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I need to determine the boundary loop polygons to represent the furniture and equipment family instances for manipulation on the mobile device.

Before I can start extracting their geometry, I need to access the objects themselves, i.e. determine which family instances are contained in the selected room.

As always, we use a filtered element collector to access the Revit database elements.

I try to apply as many quick filters as possible first, and then potentially refine the results adding slow filters and possibly even additional tests in .NET using LINQ or explicit coding.

In this case, I came up with the following sequence of filter tests which seems to fit my needs:

• Not ElementType
• View independent
• Family instance
• Bounding box intersects outline of the room's bounding box

The first two may or may not be superfluous, actually, but they do no harm either.

For the last test, I query the room bounding box, convert it to an Outline, and use that to set up a BoundingBoxIntersectsFilter. It might be possible to implement something stricter than this, or use a BoundingBoxContainsPointFilter instead.

Currently, the category and other properties are not checked at all. Once I know more exactly what kind of family instances I need, I would add those.

All of these are quick filters.

Since the room bounding box may be much larger than the room itself, for instance for an irregularly shaped or long, narrow, diagonal one, I definitely need to post-process the results with a more precise containment test. It could be purely geometric, e.g. using the point in polygon containment algorithm as in the room in area predicate, or based on other data.

I chose to implement this by checking the family instance Room property. This test could probably also be moved into a filter, e.g. a parameter filter, which would significantly improve its efficiency by avoiding marshaling the data from internal Revit to the external .NET space before checking and potentially rejecting it. See below for further considerations on using this property.

The method currently looks like this:

/// <summary>
/// Return the element ids of all furniture and 
/// equipment family instances contained in the 
/// given room.
/// </summary>
List<Element> GetFurniture( Room room )
{
  BoundingBoxXYZ bb = room.get_BoundingBox( null );
 
  Outline outline = new Outline( bb.Min, bb.Max );
 
  BoundingBoxIntersectsFilter filter
    = new BoundingBoxIntersectsFilter( outline );
 
  Document doc = room.Document;
 
  // Todo: add category filters and other
  // properties to narrow down the results
 
  FilteredElementCollector collector
    = new FilteredElementCollector( doc )
      .WhereElementIsNotElementType()
      .WhereElementIsViewIndependent()
      .OfClass( typeof( FamilyInstance ) )
      .WherePasses( filter );
 
  int roomid = room.Id.IntegerValue;
 
  List<Element> a = new List<Element>();
 
  foreach( FamilyInstance fi in collector )
  {
    if( fi.Room.Id.IntegerValue.Equals( roomid ) )
    {
      a.Add( fi );
    }
  }
  return a;
}

Family Instance Room Property Considerations

For the final test whether the family instance lies inside the selected room, I simply use the FamilyInstance.Room property.

I am aware that there may be some issues with the Room property and its phase dependency, and Patrick Rosendahl implemented a more reliable DetermineRoom method to find a containing room for a given element under all circumstances. In a complex model, I might have to add such enhancements to my approach.

Considerations Processing a Complete Model

Another issue is that the filter I present above searches for the family instances on a room by room basis.

This is fine as long as I am just looking at one single room.

If I wished to process all rooms of an entire large model, I would definitely approach this completely differently. For instance, I might select all family instances of interest in the entire model, determine the containing room for each one of them, and then invert that relationship to obtain a list of instances for each room.

Revit 2014 and Supporting Columns

Revit 2014 Announced

As you probably noticed by now, Revit 2014 has been announced. Here are the main product features:

• Design
  • Enhanced Autodesk Exchange
  • Dockable window framework
  • New stairs and railings
  • Temporary view templates to change view properties temporarily
  • Point cloud improvements improve appearance and controls of point clouds
  • Parameter variance for groups to vary the value of parameters assigned to groups
  • New air terminal on duct enables placement of air terminal device on duct face
  • New angle constraints to restrict angles for pipe, duct, and cable tray
  • Cap open ends of pipe or duct content quickly
  • CSV file removal project, embedding the data into families
  • New plumbing template
  • New rebar placement constraints customization
  • Reinforcement enhancements with more rebar options
• Documentation
  • Non-rectangular crop regions
  • Split elevations
  • Alternate dimensions
  • Improved rebar tagging to annotate multiple elements with a single tag
  • Improved positioning of beams and braces
  • Enhanced schedules providing greater control of schedule formatting
• Visualization
  • Displaced views enable creation of displaced or exploded building design views
  • Enhanced visualization
  • New rendering to reduce project costs with cloud-based rendering
• Analysis
  • New building element energy analysis
  • Enhanced structural analytical model
  • New duct and pipe calculations to API

Each and every one of these is really exciting in itself, and almost all include or are even based on enhanced API support. Some of the ones that seem most exciting to me are the non-rectangular crop regions, parameter variance for groups, enhanced schedules, displaced views... well, as said, they are really all very exciting.

And this is not even mentioning some of the new API features, such as the possibility to launch a Revit command and control copy and paste operations. I will get to all that real soon now.

As Harry puts it, the Revit 2014 API is going to blow your faces out :-)

Determining the Columns Supporting a Beam

Still, ignoring all that busy-ness for the moment, I chug along and return to a topic similar to my discussion on retrieving all touching beams.

In that post, I showed how to recursively traverse a collection of beams and detect the neighbouring ones at each end using an ElementIntersectsSolidFilter with a sphere.

Today I explore the task of determining the columns supporting a selected beam using various different methods.

• Columns supporting a selected beam
• Solid and element intersection
• Bounding box filter tolerance
• Moving the beam downwards in a temporary transaction
• GetGeneratingElementIds
• Cylinder Along Location Line Offset Downwards
• Find references via ray casting
• Sweep Along Location Curve Offset Downwards
• Conclusion and source code

Columns Supporting a Selected Beam

Here is a view of a simple sample model:

The task at hand is to pick the indicated beam and report the columns supporting it:

Simple, ain't it?

Solid and Element Intersection

Initially, I made some further attempts and experiments using the ElementIntersectsSolidFilter and ElementIntersectsElementFilter functionality.

The sample provided includes code exercising these tests and also the original bounding box implementation. It is enclosed in 'if' statements checking the setting of the following Boolean variables:

  bool useBoundingBox = false;
  bool useSolid = false;
  bool useElement = false;

That enables them to be switched on and off interactively in the debugger, if the need arises.

Unfortunately, as it turns out, they both do not work.

The beam solid is not quite big enough to intersect the columns, because the beam is cut back so that it does not actually intersect them.

The same problem also prevents use the element intersection filter.

It would be great if there was a possibility to grow the solid just slightly, e.g. offset all its faces outwards by an inch or two or define a tolerance before executing the intersection check, like for the bounding box. Unfortunately, growing or shrinking an arbitrary solid is much harder than a bounding box and therefore not implemented.

Bounding Box Filter Tolerance

The BoundingBoxIsInsideFilter can be instantiated with an optional double tolerance value that allows control over the match criteria by using the given tolerance in the geometry comparison.

By default, the tolerance is set to zero. If the tolerance is positive, the iterated element outline may extend the tolerance distance outside of the given outline in each coordinate to be a match. If the tolerance is negative, the iterated element outline must lie at least the tolerance distance inside the given outline in each coordinate to be a match.

This is exactly what I would need here for the solid and element intersection filters as well. Unfortunately, as said, such a tolerance is not supported by the solid or element intersection filters.

Moving the Beam Downwards in a Temporary Transaction

Lacking the tolerance option, I thought that maybe it would help to move the beam down a bit, and that it would intersect the supporting columns then. Unfortunately, that does not help either.

The problem is not only that the bottom face of the beam solid may be located above the end of the supporting columns, but also that the ends of the beam are cut back to avoid intersecting the columns, so their solids do not intersect even when the beam is moved slightly downwards.

This temporary movement forces a switch from read-only to manual transaction mode, of course, even though the model is not actually modify in any way in the end.

To make sure that the movement really is executed and the model updated before checking for an intersection, I followed the advice given by Arnošt Löbel on enhancing the temporary transaction trick and encapsulated the whole operation in a transaction group. The group is rolled rolled back at the end, but, before doing so, the encapsulated temporary transaction around the movement of the beam can be committed and the updated geometry evaluated.

By the way, these changes temporarily caused an error saying "Attempted to read or write protected memory. This is often an indication that other memory is corrupt." This was probably due to accessing the list of elements generated within the temporary transaction after the transaction group is rolled back. I handled that problem by storing the element ids instead of the live elements themselves inside the transaction, and then opening the elements via their id after rolling back the changes.

As said, the temporary downward translation still did not produce any intersections.

Time for another idea.

GetGeneratingElementIds

A colleague suggested that if the beam is cut back by the columns, you can iterate over the beam geometry faces and call the Element GetGeneratingElementIds method on each one, which might return the column element ids. In this example, you might also get faces generated by joins with other beams.

I tried this, encapsulating the code in the section if( useGeneratingIds ). Unfortunately, all the generating ids belong to the structural framing or floors categories, so that does not help to determine the columns either. No columns at all are returned by this method.

Cylinder Along Location Line Offset Downwards

I then realised that I could create a much simpler independent solid shape to intersect the columns by extruding a cylinder along the beam location line, offset downwards to just below the bottom face of the beam. It might require extending a little at each end. All supporting columns should be intersected by it.

I can use code similar to the sample presented to find 3D elements by intersection.

Yay! This works!

Find References via Ray Casting

A similar approach as the solid intersection with an offset cylinder could obviously also be implemented using the ray casting functionality provided by the FindReferencesByDirection and FindReferencesWithContextByDirection methods and the ReferenceIntersector wrapper class.

I did not implement any sample code demonstrating this, because I wanted to generalise the straight beam cylinder solution to a more general arbitrary curve case.

Sweep Along Location Curve Offset Downwards

Once I had the working solution using a cylinder defined by the straight beam location line offset downwards, I realised that it might be nice to use more generic sweep along curve functionality instead. After all, the beam location curve might not be straight, and a non-linear location curve can quite simply be used to generate a non-linear solid using the CreateSweptGeometry method instead of CreateExtrusionGeometry.

My first attempt caused the CreateSweptGeometry method to throw an exception saying that "The given attachment point don't lie in the plane of the Curve Loop. Parameter name: pathAttachmentCrvIdx & pathAttachmentParam". That was my fault, though, because I was providing zero for the parameter value, which is probably the normalised curve start point parameter. When providing the raw parameter value returned by curve.get_EndParameter( 0 ) instead, all works fine.

Here is a rather unrealistic sample spline beam that I used for testing:

The algorithm reports the following supporting columns for the spline beam:

All is well.

Conclusion and Source Code

Here is the complete source code of this command, including the test branches that are disabled by default. As said, they can be enabled and tested by modifying the Boolean switches interactively in the debugger.

[Transaction( TransactionMode.ReadOnly )]
public class Command : IExternalCommand
{
  const double _eps = 0.1e-9;
 
  double SignedDistanceTo( Plane plane, XYZ p )
  {
    XYZ v = plane.Normal;
    return v.DotProduct( p )
      - v.DotProduct( plane.Origin );
  }
 
  class BeamPickFilter : ISelectionFilter
  {
    public bool AllowElement( Element e )
    {
      return null != e.Category
        && e.Category.Id.IntegerValue.Equals(
          (int) BuiltInCategory.OST_StructuralFraming );
    }
 
    public bool AllowReference( Reference r, XYZ p )
    {
      return true;
    }
  }
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
    Element beam = null;
 
    try
    {
      Selection sel = uidoc.Selection;
 
      Reference r = sel.PickObject(
        ObjectType.Element,
        new BeamPickFilter(),
        "Please select a beam" );
 
      beam = doc.GetElement( r );
    }
    catch( RvtOperationCanceledException )
    {
      return Result.Cancelled;
    }
 
    List<ElementId> columnIds = null;
 
    // Optionally switch between different tests
    // by modifying these values in the debugger
 
    bool useBoundingBox = false;
    bool useSolid = false;
    bool useElement = false;
    bool useGeneratingIds = false;
    bool useLocation = true;
 
    #region Obsolete previous attempts
    if( useBoundingBox )
    {
      BoundingBoxXYZ box = beam.get_BoundingBox( null );
 
      Outline outline = new Outline( box.Min, box.Max );
 
      ElementFilter bbfilter = new BoundingBoxIntersectsFilter(
        outline, 0.1 );
 
      FilteredElementCollector columns
        = new FilteredElementCollector( doc )
          .WhereElementIsNotElementType()
          .OfCategory( BuiltInCategory.OST_StructuralColumns )
          .WherePasses( bbfilter );
    }
 
    if( useSolid )
    {
      Options opt = app.Create.NewGeometryOptions();
      GeometryElement geo = beam.get_Geometry( opt );
      Solid solid = null;
 
      foreach( GeometryObject obj in geo )
      {
        solid = obj as Solid;
 
        if( null != solid
          && 0 < solid.Faces.Size )
        {
          break;
        }
      }
 
      ElementFilter beamIntersectFilter
        = new ElementIntersectsSolidFilter( solid );
 
      FilteredElementCollector columns
        = new FilteredElementCollector( doc )
          .WhereElementIsNotElementType()
          .OfCategory( BuiltInCategory.OST_StructuralColumns )
          .WherePasses( beamIntersectFilter );
    }
 
    if( useElement )
    {
      // Initially, no columns are found to 
      // intersect the beam. Maybe it will help to
      // move the beam down a bit?
 
      using( TransactionGroup txg = new TransactionGroup( doc ) )
      {
        txg.Start( "Find Columns Intersecting Beam" );
 
        using( Transaction tx = new Transaction( doc ) )
        {
          tx.Start( "Temporarily Move Beam Down a Little" );
 
          ElementTransformUtils.MoveElement(
            doc, beam.Id, -0.1 * XYZ.BasisZ );
 
          tx.Commit();
        }
 
        ElementFilter beamIntersectFilter
          = new ElementIntersectsElementFilter( beam );
 
        FilteredElementCollector columns
          = new FilteredElementCollector( doc )
            .WhereElementIsNotElementType()
            .OfCategory( BuiltInCategory.OST_StructuralColumns )
            .WherePasses( beamIntersectFilter );
 
        columnIds = new List<ElementId>(
          columns.ToElementIds() );
 
        // We do not commit the transaction group, 
        // because no modifications should be saved.
        // The transaction group is only created and 
        // started to encapsulate the transactions 
        // required by the IsolateElementTemporary 
        // method. Since the transaction group is not 
        // committed, the changes are automatically 
        // discarded.
 
        //txg.Commit();
      }
    }
 
    if( useGeneratingIds )
    {
      Options opt = app.Create.NewGeometryOptions();
      GeometryElement geo = beam.get_Geometry( opt );
 
      foreach( GeometryObject obj in geo )
      {
        Solid solid = obj as Solid;
 
        if( null != solid )
        {
          foreach( Face f in solid.Faces )
          {
            ICollection<ElementId> ids
              = beam.GetGeneratingElementIds( f );
 
            foreach( ElementId id in ids )
            {
              Element e = doc.GetElement( id );
              if( null != e.Category
                && e.Category.Id.IntegerValue.Equals(
                  (int) BuiltInCategory.OST_StructuralColumns ) )
              {
                columnIds.Add( id );
              }
            }
          }
        }
      }
    }
    #endregion // Obsolete previous attempts
 
    if( useLocation )
    {
      // Determine beam location curve for 
      // extrusion direction and length
 
      LocationCurve lc = beam.Location as LocationCurve;
 
      Curve curve = lc.Curve;
 
      Solid solid = null;
 
      // Handle generic curve parameters.
      // See below for simplified linear case.
 
      XYZ p = curve.get_EndPoint( 0 );
      double param = curve.get_EndParameter( 0 );
      Transform transform = curve.ComputeDerivatives( param, false );
      Debug.Assert( p.IsAlmostEqualTo( transform.Origin ),
        "expected derivative origin to equal evaluation curve point" );
      XYZ tangent = transform.BasisX;
 
      // Use bounding box to determine elevation of
      // bottom of beam and how far downwards to 
      // offset location line -- one inch below 
      // beam bottom.
 
      BoundingBoxXYZ bb = beam.get_BoundingBox( null );
 
      Debug.Assert( .001 > bb.Min.Z - bb.Max.Z,
        "expected horizontal beam" );
 
      double inch = 1.0 / 12.0;
      double beamBottom = bb.Min.Z;
 
      XYZ arcCenter = new XYZ( p.X, p.Y,
        beamBottom - inch );
 
      Plane plane = new Plane( tangent, arcCenter );
 
      CurveLoop profileLoop = new CurveLoop();
 
      Autodesk.Revit.Creation.Application creapp
        = app.Create;
 
      Arc arc1 = creapp.NewArc(
        plane, inch, 0, Math.PI );
 
      Arc arc2 = creapp.NewArc(
        plane, inch, Math.PI, 2 * Math.PI );
 
      profileLoop.Append( arc1 );
      profileLoop.Append( arc2 );
 
      List<CurveLoop> loops = new List<CurveLoop>( 1 );
      loops.Add( profileLoop );
 
      // Switch this on to handle a straight beam as 
      // a separate simplified case using 
      // CreateExtrusionGeometry instead of the 
      // generic CreateSweptGeometry solution.
 
      bool checkForLine = false;
 
      if( checkForLine && curve is Line )
      {
        XYZ q = curve.get_EndPoint( 1 );
        XYZ v = q - p;
 
        Debug.Assert( 0.01 > v.Z,
          "expected horizontal beam" );
 
        Debug.Assert( v.IsAlmostEqualTo( tangent ),
          "expected straight beam vector to equal start tangent" );
 
        solid = GeometryCreationUtilities
          .CreateExtrusionGeometry( loops, v, v.GetLength() );
      }
      else
      {
        // Offset location curve downward 
        // one inch  below beam bottom face
 
        XYZ offset = arcCenter - p;
 
        transform = Transform.get_Translation(
          offset );
 
        CurveLoop sweepPath = new CurveLoop();
 
        sweepPath.Append( curve.get_Transformed(
          transform ) );
 
        solid = GeometryCreationUtilities
          .CreateSweptGeometry(
            sweepPath, 0, param, loops );
      }
 
      ElementFilter beamIntersectFilter
        = new ElementIntersectsSolidFilter( solid );
 
      columnIds = new List<ElementId>(
        new FilteredElementCollector( doc )
          .WhereElementIsNotElementType()
          .OfCategory( BuiltInCategory.OST_StructuralColumns )
          .WherePasses( beamIntersectFilter )
          .ToElementIds() );
    }
 
    int n = (null == columnIds)
      ? 0
      : columnIds.Count<ElementId>();
 
    string s1 = string.Format(
      "Selected beam is supported by {0} column{1}{2}",
      n,
      ( 1 == n ? "" : "s" ),
      ( 0 == n ? "." : ":" ) );
 
    string s2 = "<None>";
 
    if( 0 < n )
    {
      uidoc.Selection.Elements.Clear();
 
      foreach( ElementId id in columnIds )
      {
        Element e = doc.GetElement( id );
        uidoc.Selection.Elements.Add( e );
      }
 
      s2 = string.Join( ", ",
        columnIds.ConvertAll<string>(
          id => id.IntegerValue.ToString() ) );
    }
 
    TaskDialog.Show( s1, s2 );
 
    return Result.Succeeded;
  }
}

For your convenience, here is GetBeamColumns06.zip containing the complete source code, Visual Studio solution and add-in manifest of the GetBeamColumns external command.

I hope you find this both interesting and useful as a basis for your own variants.

Rename View by Matching Elevation Tag with Room

Today is the last morning meeting with my European DevTech colleagues here in Brittany, and time to travel back to Switzerland.

Before leaving, here is a useful real-world productivity tool by Trevor Taylor of ZGF, Zimmer Gunsul Frasca Architects LLP, with his own description of the task and its solution:

The task I want to address is to match interior elevation tags with the rooms they fall inside.

This is used to track back and rename the corresponding views.

Naming interior elevation views is a major time-burner as there can be thousands of views in a project to rename, and they have to be coordinated when the room numbers or names change. If we don’t tie view names to rooms, we have no hope of ever keeping track of so many views.

I originally attacked this by trying to determine the location of the view tags in the model, but had to give up on that one.

Ben Bishoff of Ideate gave me the idea to approach the problem from the view rather than from the interior elevation tag, so I worked backwards from the view cropbox property using the RevitLookup app and arrived at this simple solution:

1. Collect all views of class ‘ViewSection’, then filter down to those of ‘Interior Elevation’ type:

  FilteredElementCollector collector
    = new FilteredElementCollector( m_doc )
      .OfClass( typeof( ViewSection ) );
 
  foreach( ViewSection current in collector )
  {
    ViewFamilyType vft = m_doc.GetElement(
      current.GetTypeId() ) as ViewFamilyType;
 
    if( null != vft
      && vft.Name == "Interior Elevation" )
    {
      m_int_elevation_views.Add( current );
    }
  }

2. Construct a point at the midpoint of the front bottom edge of each interior elevation view's CropBox. The CropBox is conveniently relative to the projection plane of the view. X is to right, Y is up, and Z is the view depth:

  // Construct a point at the midpoint of the 
  // front bottom edge of the elev view cropbox
 
  double xmax = v.CropBox.Max.X;
  double xmin = v.CropBox.Min.X;
  double zmax = v.CropBox.Max.Z;
 
  XYZ pt = new XYZ(
    xmax - 0.5 * ( xmax - xmin ),
    1.0,
    zmin );

3. Get pt's translation to project's coordinate system:

  // Get pt's translation to 
  // project coordinate system
 
  pt = v.CropBox.Transform.OfPoint( pt );
 

That takes care of the heavy lifting. Pass pt to the GetRoomAtPoint method and you obtain the room, if there is one to get:

4. Retrieve the room:

  Autodesk.Revit.DB.Architecture.Room rm
    = m_doc.GetRoomAtPoint( pt );

It does exactly what I want it to now and will save our teams countless hours on large projects by organizing the names of interior elevation views by room name:

Here is a complete sample project including a test model in case you’d like to check it out yourself.

Many thanks to Trevor for this useful tool, his research, implementation, and generous sharing.

Before I sign off, here are two other nice pointers, not related to Revit:

Au Bout du Monde and Super-Sonic Stereo

Brittany is at the end of the earth, or Finisterre, au bout du monde, and I have seen many restaurants, a parking place, and a number of other establishments named after that around here.

That reminded me of one of my favourite humorous YouTube films, a Russian cartoon also named Au Bout du Monde, by Konstantin Bronzit:

It was very fitting to share with my colleagues, since two of us are Russian as well. We enjoyed it a lot, and I hope you like it as much as I do.

While we are at it, yesterday, my son Christopher pointed out another quite nice blog with explanations of what-if questions, the most recent one featuring sound sources, asking what if my stereo flew around at super-sonic speed? I enjoyed that as well, and so might you.

Last but not least, today is the first day of spring and vernal equinox!

Off we go to the airport...

Determining Purgeable Elements

A question that crops up from time to time and is rather hard to answer exactly and exhaustively is on purgeable elements:

Question: What is the best way to get all of the elements that can be purged? I can use WhereElementIsElementType filter to return all types, and WhereElementISNotElementType to return instances, but comparing the two lists does not leave me with the purgeable result. I could compare individual lists of types (i.e. family symbol and family instance), but that seems prone to error. Is there any good way to get this information out of the model?

Answer: Yes, the Revit API does not currently provide any direct method to determine this.

Let's see what can be done about it anyway already.

When you say "all of the elements that can be purged", that can be a pretty huge task.

I would suggest breaking that down into individual sub-tasks for different types of purgeable elements, which will require pretty different handling.

For example, I implemented a method DeleteUnnamedNonHostingReferencePlanes to find and delete all reference planes not hosting any elements.

An explicit reference to the term purge is used in the post on removing unused text note types.

One way to determine whether a certain element A is required by another one B is to delete A and check the return value of the Delete method, which provides a list of deleted element ids. In some cases, B is deleted as well, and its element id is included the resulting list of deleted element ids. This is used by the object relationship analyser (VB).

The deletion can be made temporary by encapsulating it in a transaction that is later rolled back. Here is a discussion of the temporary transaction trick including a list of numerous usage examples, and later touched up slightly.

Unfortunately, of course, this method becomes extremely slow in a large model with each deletion taking place in its own transaction and then rolled back. Wrapping it all in one single transaction will essentially deleting the entire model, which causes other problems is also not very useful, so this idea may not really be very feasible for the task at hand.

When you do have access to a one-way relationship between two classes of objects, e.g. pointers from doors, windows and openings hosted in walls to their respective wall host elements, you can easily invert the relationship to determine the list of hosted object for each host. This is demonstrated in my discussion of the relationship inverter in one of the very first blog posts.

Taking a look at family types only, which is a small subset of the potentially purgeable elements, a similar one-way relationship as the one between hosted objects and their hosts is defined between non-element types and types, since the former provide a property named GetTypeId pointing to the type. You could make use of this in a similar manner to find all unused types as follows:

1. Determine all non-type elements using WhereElementISNotElementType
2. Iterate over all non-type elements. Determine the element id of each one, and build a dictionary D of the inverse relationship, mapping type element id to a list or the elements using that type.
3. Use WhereElementIsElementType to determine all element types. Iterate over them. For each type, check D to see how many elements are referencing it. If D has no entry for this type, it is not being used and can be deleted.

There is no guarantee that this will really work, though, since there may be any number of exceptional situations that need to be handled differently on a case-by-case base.

You can try it out, though, see whether you corrupt the database in any way, test thoroughly, possibly add handling of all special cases that you encounter, and maybe achieve your goal in the long run.

Unfortunately, there is currently no API access to the list of objects or categories searched by the built-in purge functionality, and the logic used for it is non-trivial.

Definitely, a number of special cases need to be handled, and there are some things that cannot be determined using the method described above.

For example, there are no instance placements of materials, so you have to search through instances placed in the model and for each element determine whether the material is used by it or not. This also leaves out materials that are set for type parameters on types that have not been used but are loaded into the model.

Retrieving Schedules on a Sheet

Guy Robinson recently explained an easy way to access all elements in a schedule.

Victor Chekalin picked up and expanded on that.

Here is his solution to retrieve all schedules in a view and elements from a schedule. In his own words:

One wonderful day I had to retrieve schedules which are presented on a sheet:

At first I looked at the Revit API Help but unfortunately there is no method such as GetSchdulesOnView in the ViewSheet class. There is no explicit way to get it. After a couple of hours trying to achieve that I need I encountered Guy's simple solution to access all elements in a schedule. The solution is use FilteredElementCollector and pass in the element id of the view in which you want to collect elements.

I created the following simple extension method GetSchedules to get schedules on view:

  public static class ViewSheetExtensions
  {
    public static IEnumerable<ViewSchedule>
      GetSchedules( this ViewSheet viewSheet )   
    {
      var doc = viewSheet.Document;
 
      FilteredElementCollector collector =
        new FilteredElementCollector(
          doc, viewSheet.Id );
 
      var scheduleSheetInstances =
        collector
          .OfClass( typeof( ScheduleSheetInstance ) )
          .ToElements()
          .OfType<ScheduleSheetInstance>();
 
      foreach( var scheduleSheetInstance in
        scheduleSheetInstances )
      {
        var scheduleId =
          scheduleSheetInstance
            .ScheduleId;
 
        if( scheduleId == ElementId.InvalidElementId )
          continue;
 
        var viewSchedule =
          doc.GetElement( scheduleId )
          as ViewSchedule;
 
        if( viewSchedule != null )
          yield return viewSchedule;
      }
    }
  }

It can be used like this:

  var schedules = viewSheet
    .GetSchedules()
    .ToList();

  foreach( var viewSchedule in schedules )
  {
    // Do something
  }

Here is the demo result:

But I decided not to stop and go deeper. The next step is to get all elements which are involved in a schedule. The approach is the same as with schedules. Using FiltereredElementCollector but instead of the ViewSheet element id we pass in the ViewSchedule id.

The extension method is similar:

  public static class ViewScheduleExtensions
  {
    public static IEnumerable<ElementId>
      GetElementIdsInSchedule(
        this ViewSchedule viewSchedule )
    {
      var doc = viewSchedule.Document;
 
      FilteredElementCollector collector =
        new FilteredElementCollector(
          doc, viewSchedule.Id );
 
      var elementIds = collector
        .WhereElementIsNotElementType()
        .ToElementIds();
 
      return elementIds;
    }
  }

But there is an additional little nuance. If I retrieve elements from a material takeoff schedule, the method will return all materials in the project together with other elements. The solution is to just skip all elements which are materials:

  foreach( var id in elementIds )
  {
    var element = doc.GetElement( id );
 
    if( element is Material )
      continue;
 
    // Do something
  }

Here is the result of my demo project:

I attached the demo Visual Studio solution and Revit project.

I hope this information will useful for developers.

Have a nice day,
Victor.

Delux Database Enabled Loading and Updating

This paper by Steven Rowland, Interior BIM Manager in a hospital in Stockholm, Sweden, describes a novel method to extend database functionality for a "smart" loading and updating process in very large Revit projects.

The method is designed solve a somewhat unique problem, but the resulting solution has interesting possibilities for other projects of all sizes. Here it is:

Database Enabled Loading & Updating eXperiment – DELUX Copy/Paste

By Steven Rowland and Fredrik Sjödén.

This short paper describes a novel method to extend database functionality for a "smart" loading and updating process in a very large Revit project. It builds upon the white paper on database integration by Miroslav Schonauer of Autodesk.

Summary Description

The DELUX copy/paste method uses an external database definition to duplicate floor plans, in whole or in part, to multiple Revit models or floor plans, with the ability to update changes as required. This includes walls, doors, windows, generic models, detail groups, etc., as well as associated annotation. The resulting duplicated floor plans can be updated or refreshed from the database definition as changes occur in the source file. All Revit content in the copied floor plans is live, i.e. nothing is grouped or in links.

Project Description

It is important to understand the kind of project that this was developed for, because we had special circumstances that pushed us towards finding the kind of crazy solution that we developed. We have a very large hospital project, with over 300,000 sq. meters of new construction. The project was divided into 17 main Revit model files, and several more supporting model files. Each of the main Revit files hover between 300-800 megabytes.

In addition, the project is a "fully loaded" project, meaning that all equipment, furnishings, and building elements are loaded into every room (11,000+ rooms). In addition, various other data types are fully implemented into the BIM model. We are required by contract to not use typical floor plans, even where floor plans are repetitive. Also, it is good to understand that this is a live model, which is actively being used for construction and coordination during the design process over several years of continuous design and construction. Eventually the fully loaded BIM model will be handed off to facilities management.

The Problem

The problem we had was this: we have numerous (14) floor plans that are identical or nearly identical with minor differences. These repetitive floor plans are spread across multiple Revit models (4 models). Because of the "fully load" requirements I described above, we were required to fully document each plan completely. On normal projects, this would be accomplished by using Revit Groups or Links. However, both of those methods were unavailable to us, because we have extensive database connections and collaboration methods (IFC, Navis) that do not cooperate with the limitations of Revit Groups or Links. We needed a method that would allow us to have "live" Revit content on multiple plans (no groups or links), and manage the repetitive floor plans in a time efficient way. We wanted to quickly and accurately duplicate entire floor plans and manage change during the design process in an efficient BIM way. We don't like to do the same thing more than twice, and 14 times over is simply too inefficient.

DELUX Copy/Paste

Step one – Mark elements for the database definition – On a Source Plan, we marked each model element with a DELUX parameter to identify that it was a member of the database definition. We included all doors, windows, walls, openings, generic models, furniture, casework, equipment, etc. (Note: ceilings were not included because of API limitations. Also note that room objects are not included.)

Step two – Create a relative coordinate system – We added a simple annotation object to mark a base point that we would measure x,y coordinates from. We could have used the project basepoint, however we felt that a relative coordinate system would offer more flexibility.

Step three – Export to a database –We programmed an add-in that would identify all the members of the DELUX group, and use the relative base point to measure x,y coordinates. The add-in exports all information associated with the model elements, including x,y coordinates, all parameter values, sizes, shapes, rotations, checkboxes, worksets, and everything else we could find through the API. The exported information is formatted as binary code. We had a database available that we use for other purposes, so we put the DELUX information there also. The add-in also adds another parameter to all of the source model elements – UniqueID. We will use this UniqueID parameter later for the updating process. (Note that all annotation for any given model element is exported from all views, and not just the active view. Also note that we are not exporting dimensions yet, but we are looking to explore those possibilities also.)

Step four – Target Plan – We prepare the target plan by placing a target annotation family to mark the relative coordinate. In our project we used a stairwell as the common base point. Any model elements that we wish to replace with the database definition are then marked with the same DELUX parameter that was used in the source file.

Step five – Initialize and precheck – The DELUX add-in does two things when it starts. First it checks for and then adds any missing shared parameters to the target Revit file. Second it performs a precheck to ensure that all required families are present in the target file. We have systems that can automatically load most types of families, however the precheck generates a pop-up and text file that lists the missing families, if any. At this point the user can either proceed with insertion or cancel out of the function and manually load the missing families into the target Revit file.

Step six – Press the shiny button – Now we can tell the add-in to begin inserting the database definition. We begin with the walls, and the function uses the API to insert them according to the relative coordinates we provided. Then it proceeds with doors, windows, and openings. After that all other Revit families are added. All content is inserted in the correct location, orientation, workset, etc., with all parameters and options preserved from the source file. (Note: walls are inserted relatively slowly on the first insertion. This can depend upon the size and complexity of the model, and is constrained by Revit calculating room bounding. We have tried to find various ways around this constraint, and, while there are possibilities, the walls are the slowest to populate from the database definition. In our experience on large model files (500+mb) the insertion rate is about 20 walls per minute. This is accelerated substantially when updating, as I will discuss later.)

Step seven – Annotate – We have a second add-in for inserting annotation. Upon initializing, the user chooses the DELUX group, and the interface shows which annotation views are available from the source file. The user then chooses an active view to receive annotation and presses the shiny button. All annotation from the selected source view is inserted in the correct position and orientation. This can be repeated multiple times for as many source/target pairs as are required.

Step eight – Update – As previously noted, each source model element receives a UniqueID parameter. The same UniqueID parameter from the source is written to each model element in the target plans. By using this parameter we are able to evaluate and match the source and target elements. The update process is similar to the insertion process. If we make changes to the source plans, we export the DELUX group again to the database. In the target file, we run the insertion function same as before; however this time the function uses the UniqueID parameter to compare each element to the new database definition. If the element has not changed, then it is ignored for updating. If the element has changed then it is removed and a new element is inserted in its place. It continues until the floor plan is refreshed. This process is much faster than the initial insertion process.

Implications

That is the entire function, with a few more features that I have not described here. It is still under development, so we have hope for expanding and refining it in various ways. The beauty of this system is that it allows us to manage multiple identical target plans from one source plan, and be certain that any changes are reproduced accurately across multiple Revit files without using Revit Groups or Links. Extending this to annotation opens the possibility of substantially reducing the time required to prepare documentation. This can all be updated over time, and doesn't interfere with our collaboration methods, or other database linkages; in fact we have found ways of using it to reduce work in other areas by leveraging the matched-up UniqueID of source/target. All of this is accomplished through the use of external database connections, and some very clever coding ;)

So what do you think? In some ways we are reinventing the wheel – however we had special needs that led us to this solution. I'd love to hear your opinion, if you have time.

Addendum: I continue to imagine more ways of extending the method. There are, of course, some limitations with our current approach. The biggest one is that the update process is currently a “remove-and-replace” approach, meaning that the new updated content has a new GUID, which can cause problems. The source GUID is written to a parameter on each target element, thus providing the source/target pairing. In the future I would like to provide the option to update parameters or x,y location only, without removing and replacing the content. This will require us to make some changes in how we store information in the database, but could work.

Now, let's return to a couple of other interesting items...

Autodesk University 2012 Classes Now Available

The Autodesk University 2012 classes are now available, both from the live Las Vegas and the AU Virtual conferences.

They are provided at no cost via the class catalogue on the AU website, available to anyone with an AU account.

If you don't have an account, you can sign up for free at any time.

Here are all the details.

Setting a Structural Framing Tag Leader Arrowhead

In a recent AEC DevBlog article, Saikat Bhattacharya demonstrates how to set the leader arrowhead for a structural framing tag.

His sample code first retrieves all arrowhead definitions, which are ElementType instances whose family name is "Arrowhead". They are obtained using a filtered element collector and a parameter filter testing the built-in parameter ALL_MODEL_FAMILY_NAME for that value. Once the desired arrowhead is found, the IndependentTag built-in parameter LEADER_ARROWHEAD is set to its element id.

Using DMU to Track Changes to a Custom Project Parameter

Another of Saikat's articles discusses the implementation of a dynamic model updater for project parameters. It checks whether a specific shared parameter has been attached to the door category. If so, a dynamic model updater is created and set up to be triggered by changes to that specific parameter on door instances.

Thank you for these two nice posts, Saikat!

The Useful Log4Net Logging Tool

Sometimes you need to obtain information about what you add-in is actually doing, possibly even from a customer, e.g. if something unexpected happens.

For this purpose, Rudolf Honke recommends using log4net. It comes equipped with a very helpful tutorial as well.

Changing Viewport Type

Here is a question on setting the type of an element by using the built-in ELEM_FAMILY_AND_TYPE_PARAM parameter value, explored by Bettina Zimmermann of NTI Cadcenter A/S:

Question: I'm inserting viewports on sheets and I'd like to change the viewport type to my own defined type.

How can I this programmatically?

By default, the API call creates a new viewport with type "Title w Line". I'd like to change that to e.g. my own type "Test".

Here is my own self-defined viewport type "Test":

I created it manually by pressing Duplicate.

The API method to create viewports does not support any viewport type parameter:

  Autodesk.Revit.DB.Viewport.Create(
    Document, viewSheet.Id, View.Id, zero )

I hope the viewport type can be changed in some other way.

Answer: When dealing with views and viewports, one of the first places to take a look is Steve Mycynek's AU class CP3133 Using the Revit Schedule and View APIs, which demonstrates just about everything you can do with the Revit View API.

Further, I would suggest that you explore the elements of interest in depth using RevitLookup.

The Element.GetTypeId method may provide read access to the data you seek. Unfortunately, of course, it is read-only. Maybe you can find some parameter that also provides access to this data?

Response: I did indeed find a parameter, well hidden in an unexpected location.

My first thought when searching for it is that the viewport is a system family, just like a wall, and walls allow you to change their type by setting wall.WallType = newWallType.

Walls also expect a type argument when a new wall is created:

  DB.Wall.Create( Document, Line, WallType.Id,
    Level.Id, 11, 0, False, IsStructural );

However, as said, the Viewport Create method does not take any type argument:

  Autodesk.Revit.DB.Viewport.Create(
    Document, viewSheet.Id, View.Id, zero );

In spite of this, the parameter I found that I can use for this is BuiltInParameter.ELEM_FAMILY_AND_TYPE_PARAM.

I created a VB.NET sample add-in ChangeViewPortType to demonstrate its use. Here is how to use it:

• Set a sheet view active with two viewports on it – could be two floor plans on a sheet.
• Change one of the viewports to another type – see below.
• Select both viewports and run sample project – the last selected viewport will be changed to have the same type as the first.

Here is a sheet with a viewport.

The default type of a newly created viewport is 'Title w Line'; I made a new type called 'Test' that has no 'Title' and 'Extension Line'. 'Title' and 'Extension Line' is the circle with a line and some text:

I made the type by clicking 'Edit Type' and duplicate.

Many thanks to Bettina for her exploration and thorough documentation!

Addendum: As pointed out below by Alexander Buschmann, the Revit API also provides the more user-friendly Element.ChangeTypeId method to directly change the type of any element having a type, with no need to go through the parameter to access it. Thanks, Alexander, for adding that!

GetInstanceGeometry Overhead and Invalid References

I made it back safe and sound to Switzerland from the developer conferences, and I note that this special pivotal day – the winter solstice – seems to be progressing normally and we all survived in spite of the end of an era in the Maya calendar.

Thus we can continue growing our understanding of the Revit API, as well as attending to other important business here on our lovely planet.

The GeometryInstance GetInstanceGeometry method returns the geometry of a family symbol. More precisely, according to the Revit API help file RevitAPI.chm documentation, it computes the geometric representation of the instance.

Computes really means computes, and incurs some significant overhead, as emphasised by the help file remarks, which state:

The geometry will be in the coordinate system of the model that owns this instance. The context of the instance object (such as effective material) will be applied to the symbol. Note that this method involves extensive parsing or Revit's data structures, so try to minimize calls if performance is critical. Geometry will be parsed with the same options as those used when this object was retrieved. This method returns a copy of the Revit geometry. It is suitable for use in a tool which extracts geometry to another format or carries out a geometric analysis; however, because it returns a copy, the references found in the geometry objects contained in this element are not suitable for creating new Revit elements referencing the original element (for example, dimensioning). Only the geometry returned by GetSymbolGeometry with no transform can be used for that purpose.

This is also covered by the Developer Guide section on geometry instances.

Now a poor hapless (or not so hapless, in fact) developer ran into an example where the invalid references returned by this method cause a significant problem, providing a welcome opportunity to highlight the importance of avoiding use of this particular method for that kind of use:

Question: I am using the analysis visualisation framework AVF to paint some transient graphics a given face.

When I use the following line to apply the AVF to the face, the behaviour is correct:

  int idx = sfm.AddSpatialFieldPrimitive(
    face, Transform.Identity );

When this call is used instead, however, Revit throws an exception saying that the reference must point to either a Face or a Curve visible in the view:

  int idx = sfm.AddSpatialFieldPrimitive(
    face.Reference );

This message is incorrect, because the Face is visible in this view.

I really need the face reference call to work so that the AddSpatialFieldPrimitive method overload taking a reference and SpatialFieldPrimitiveHideMode can be used, i.e.

  AddSpatialFieldPrimitive(
    Reference,
    SpatialFieldPrimitiveHideMode )

Answer: The behaviour you observe is caused by your use of the GeometryInstance GetInstanceGeometry method, and then asking AVF to pull references from that geometry.

As stated in the description quoted above, these references are invalid.

If you simply change your macro to use GetSymbolGeometry instead, the AVF results will be correctly painted on the faces.

Some other operations besides AVF that also need these references to be correctly obtained from GetSymbolGeometry include dimensioning, face based family creation, and sketch plane creation.

GetInstanceGeometry is a shortcut to get 'in-place' geometry for operations like export to another format, Boolean operations with another solid, or other geometry tools that don't need the connection back to the original element.

Many thanks to Scott Conover for clarifying this!

Survey and Project Base Point

Happy Thanksgiving!

I am on the road to Las Vegas now, gearing up for last-minute AU preparations. No actually, I am pretty much set to go. Other upcoming developer conferences still require some work, though.

Meanwhile, here is some useful information on survey and project base points gathered by my colleague Joe Ye:

Question: We need to work with the project base point and the survey point to design platforms in real-world coordinate systems and load survey data from DXF and DWG files containing geo-referenced coordinates. We therefore wish to use the Revit API to work with the project base point and the survey point.

Could you please explain how to programmatically achieve the following?

• Get and set the location of the project base point and the survey point.
• Get and set their parameters (shared coordinates).
• Lock and unlock these points.

Additionally, here are a few further questions to improve our understanding of this topic:

1. In Revit we are limited to a distance of 10 kilometres. Does this mean that it is necessary to move the survey point together with the shared coordinates of real coordinate systems? I successfully placed a platform into a project 25.000 kilometres distant from the project base point (0,0,0) and the survey point (0,0,0).
2. What is the relation between the shared site (the parameters of the point) and the location of the survey / project base point?
3. Am I right in my assumption that the survey point changes it's parameters (shared site) when moved depending on whether it is "locked" or not?

Answer: The Revit API for shared coordinates is currently still a bit limited. Here is some of the available functionality:

• Document.ProjectLocations will return all of the ProjectLocations (sites) in a project.
  • These provide Name and ProjectPosition properties that can be used to change the name or position of the site.
• The base point and survey point can be retrieved through a FilteredElementCollector for BasePoints.
  • The BasePoint whose IsShared property is true represents the survey point.
  • Each BasePoint has a Location property that you can set to move the point.
  • The clipped/unclipped state of the base and survey points cannot be set via the API. You can pin them using the Element.Pinned property.
• You cannot currently access the shared location of a Revit or DWG instance via the API.
• You cannot establish a shared-coordinates relationship with a link instance via the API. If the link is already using shared coordinates, then moving the survey point will move the link.

To answer your other questions:

1. The distance limit restricts you from moving the coordinate system origin point more than 10k away from its origin. It is still permissible to place Elements far away from the coordinate origin.
2. There isn't necessarily any relationship. Sites are locations you define as you like. They can be placed anywhere.
3. Yes. If the survey point's clipped, then it is 'attached' to the world, and when you move it, you move the world with it. If you want the survey point to represent some location other than (0,0,0), you can unclip it to move it and nothing else.

Many thanks to Joe for digging this up!

BIM for Infrastructure White Paper

Talking about survey points and stuff like that, a new white paper has just been released explaining the use and advantages of BIM for infrastructure: BIM for Infrastructure: A vehicle for business transformation discusses BIM as the vehicle by which the business of planning, designing, building, and managing the world's infrastructure will be transformed to deliver higher productivity, quality, and cost-effectiveness.

ODBC Export

A recurring topic is programmatic ODBC export.

Here is a typical query on this topic with an answer by Saikat Bhattacharya:

Question: Is there a way to export the whole Revit database to an external database such as MSsql via the ODBC link, similarly to the manual process or using DBLink, but avoiding all the dialogues for choosing the ODBC connection etc.? I would like to set up the connection programmatically in .NET instead.

Answer: The Revit API provides direct access to the underlying data. You can implement your own export functionality to any external database including MSsql. How to implement this is completely up to you to decide.

The API provides access to the data in the model that might need to be included in the export. With the data available, the connection can be set up and desired data exported to any external database.

The Revit 2010 SDK still included the RDBLink sample, so that code is available in case of interest. Due to its size and complexity, it was later promoted to a subscription feature and removed from the SDK. If you like, you could migrate the old Revit 2010 code to the current version and use it as a basis for your own implementation.

Here are a couple of discussions related to this topic:

• RDB Link tool on Autodesk Labs.
• Integration with a database or ERP system.
• In-depth analysis of integrating with external databases and other data sources.
• Adding a column to RDBLink export.
• Exporting parameter data to Excel, and re-importing.

Many thanks to Saikat for putting together this overview!

Updater Queues Multi-Transaction Operation for Idling

I recently pointed out that certain operations require multiple transactions to complete.

The dynamic model updater framework DMU, on the other hand, takes complete control over the transaction handling, making it impossible to incorporate such a multi-transaction operation.

The updater framework is designed to enable an add-in to incorporate its own additional behaviour into a running transaction to react to changes in the model. The advantage is that the entire operation including the custom add-in behaviour is encapsulated in one single transaction. This comes at a price, as said: the add-in has no control whatsoever over the transaction management. It thus also obviously cannot add additional transactions into the process.

Let me present a powerful and generic workaround to this limitation, suggested by Rudolf Honke.

He ran into this issue when trying to group elements in an updater, for instance for his dynamic insulation and dynamic arrangement of elements on a terrain surface tools. The dynamic insulation group behaves almost like a custom entity in AutoCAD:

The element arrangement on terrain can be used to place trees, lampposts, and other objects to follow a curve and update automatically to changes in the curve:

The narration for these two videos is in German, by Mr Honke himself. The dynamic insulation tool is also available in an English version, but that has not yet been uploaded.

Both of these tools generate and handle groups of elements and react dynamically to later changes of the model.

The reaction makes use of the DMU; there is no other choice. However, the entire update operation requires ungrouping, modifying and regrouping of elements and cannot be achieved within the single transaction provided.

Additional transactions in the IUpdater would be required to handle this gracefully.

In lack of this, here is Rudolf's workaround:

1. In the updater, save a list of elements requiring update.
2. Subscribe to the Idling event.
3. In the Idling event handler, call the standard add-in command that has no restrictions on its transaction handling.
4. In the command, process the queued up elements and clear the list.
5. Unsubscribe from Idling.

In the actual implementation, the elements obviously maintain some data about their relationships, so the modification of an element can easily discover which other elements are affected.

Here are a few more details and several reasons why this is necessary:

• The insulation tool needs to both delete and create new DetailCurves. It also needs to create a new HermiteSpline which is not a DetailCurve at all, by the way. By the way, accessing its ElementId during the insulation creation process requires a (temporary) DocumentChanged event, which is another topic that we will not explore any deeper here. To avoid ForbiddenForDynamicUpdateExceptions, the creation is placed in a completely new transaction.
• The dynamic fence and arranging-items-on-terrain tools require creation of new FamilyInstances, which should be avoided in the IUpdater context, as stated in the Revit API help file RevitAPI.chm.
• The error handling needs to be able to use FailureHandlingOptions, which again means that the add-in has to have full access to the transaction itself.

The IUpdater context is fine for just setting parameters, but these tools need more than that, e.g. deleting elements, creating new ones, adding extensible storage data to handle the element connection logic, handling Failures, etc.

I recently ran into a different case where a developer was trying to make use of the InstanceVoidCutUtils class to insert a void on a modified wall within the updater Execute method. This caused Revit to display an error message saying "Third party updater Xyz has experienced a problem and its action had to be canceled." Removing the one single line triggering the void generation from the updater enables to operation to complete, but the void is still missing, of course. That seems to me like a prime use case for Rudolf's approach as well.

Geometry Object Subcategory

I received and have started installing and learning to use my new laptop, which is a Mac, I'm finishing up my preparations for Autodesk University, and I'm working on preparations for upcoming developer conferences, so you can imagine there is rather a lot to do and 24 hours per day seem very limiting. I love the Unix shell! Goodbye, DOS box.

Thank goodness my colleague Joe Ye answered a case that I found interesting and would like to share with you, since Joe is busy preparing his own Chinese developer meetings and conferences:

Question: I am trying to determine the subcategory of each solid element in a family.

Can this be done using the API?

My family that has two different solids and they have different subcategories.

I want to know which solid I am looking at and figured that subcategories would be a good way to go, since they can be applied to solids in a family.

Please note that the family with the subcategories must be nested as a non-shared family and I have to find out what element geometry is what in the supercomponent family.

I know that I can find out what subcategory each solid element belongs to when I open the family, but can I do so when its loaded as well?

Is there any other way of identifying different geometry objects once a family instance has been placed in the project? Besides looking at the geometrical aspects such as volume, areas etc.

Answer: Yes, you can retrieve the solid category from the family instance in the model.

The category information is stored in the Solid object's GraphicStyle property.

The following code retrieves all the solid category names from a selected family instance:

[Transaction( TransactionMode.ReadOnly )]
public class Command : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
 
    Selection sel = uidoc.Selection;
 
    Reference r = sel.PickObject( ObjectType.Element,
      "Please pick a family instance" );
 
    Element e = doc.GetElement( r );
 
    GeometryElement geoElem = e.get_Geometry(
      new Options() );
 
    int n = 0;
    string s = string.Empty;
 
    foreach( GeometryObject obj in geoElem )
    {
      if( obj is GeometryInstance )
      {
        GeometryInstance geoInst
          = obj as GeometryInstance;
 
        GeometryElement geoElem2
          = geoInst.GetSymbolGeometry();
 
        foreach( GeometryObject geoObj2 in geoElem2 )
        {
          if( geoObj2 is Solid )
          {
            Solid solid = geoObj2 as Solid;
 
            ElementId id = solid.GraphicsStyleId;
 
            GraphicsStyle gStyle = doc.GetElement(
              id ) as GraphicsStyle;
 
            if( gStyle != null )
            {
              ++n;
              s += gStyle.GraphicsStyleCategory.Name
                + "\r\n";
            }
          }
        }
      }
    }
 
    TaskDialog.Show( n.ToString() + " Graphics Styles",
      s );
 
    return Result.Succeeded;
  }
}

Here is an example of running this and selecting one of the doors in the basic sample project:

The following materials are listed for this instance:

Many thanks to Joe for this answer!

Listing all Schedules Placed on a Sheet

Meanwhile, Saikat discusses yet another use of the temporary transaction and deletion trick to determine all schedules placed on a given sheet.

In this case, the trick is to temporarily delete the sheet and watch which schedules are wiped out by that operation.

Note that in a comment on that post, Phillip Miller points out a way to achieve the same result using a filtered element collector taking a view id argument.

Who is going to create a benchmark comparing the relative speed of these two approaches?

Beam Bottom Endpoint

Here is a nice little example illustrating different approaches to find the end point of the bottom centre line of an inclined beam.

Question: I am trying to find the coordinates of the end points of the bottom centre line of an inclined beam. Depending on the beam angle, these coordinates will change.

Here is a 3D view of the kind of situation I am looking at:

The front view looks like this with the beam end points marked in orange. The desired bottom line end points are marked by red points within the circled areas:

I am currently using the following code to retrieve the beam location line start and end points:

  LocationCurve location = beam.Location as LocationCurve;
  Curve c = location.Curve;
  XYZ p = c.get_EndPoint( 0 );
  XYZ q = c.get_EndPoint( 1 );

Answer: There are an infinite number of ways to achieve this. Here are three to start with, in order of increasing purely personal preference:

• Face iteration and project
• Parameter values and trigonometry
• Perpendicular vector

Face Iteration and Project

One way to approach this is to use the beam solid faces and projection methods provided by the Revit geometry API to calculate the desired points.

You can determine the bottom face of the beam by querying the beam for its solid, iterating over its faces, and searching for the face whose normal vector has a minimal Z value, i.e. points downward the most. I provided source code samples implementing this for the bottom and top faces of a wall.

You can then project the beam location line end points onto that face using the Face.Project method to obtain the desired bottom line end points.

Parameter Values and Trigonometry

A second solution is based on querying some of the beam parameter values and using a little bit of trigonometry.

It calculates the sides of the right angle triangle using the beam direction vector, vertical delta and insertion value and returns the beam bottom coordinate as follows in C#:

void GetBeamInsertionAndVertDelta(
  Element beam,
  double sideLength,
  out double beamInsertion,
  out double beamVertDelta )
{
  // sideLength is beam height. 
  // If there is any other element like plate to 
  // be attached to beam bottom then 
  // sideLength = beam height + plate thickness
 
  beamInsertion = 0.0;
  beamVertDelta = 0.0;
 
  if( null != beam && _eps < Math.Abs( sideLength ) )
  {
    Parameter cutLength = beam.get_Parameter(
      BuiltInParameter.STRUCTURAL_FRAME_CUT_LENGTH );
 
    Parameter stOffset = beam.get_Parameter(
      BuiltInParameter.STRUCTURAL_BEAM_END0_ELEVATION );
 
    Parameter endOffset = beam.get_Parameter(
      BuiltInParameter.STRUCTURAL_BEAM_END1_ELEVATION );
 
    double hypotenuse = cutLength.AsDouble();
 
    double side = Math.Abs( stOffset.AsDouble() 
      - endOffset.AsDouble() );
 
    double angle = Math.Acos( side / hypotenuse );
 
    beamInsertion = ( sideLength / Math.Tan( angle ) );
    beamVertDelta = ( sideLength / Math.Sin( angle ) );
  }
}

Perpendicular Vector

The simplest solution may possibly be to avoid using the beam geometry as well as the tan and sin functions and just calculate straight away based on the beam location line.

You can determine the vector perpendicular to the beam location line and pointing downward as much as possible, i.e. lying in the plane P defined by the (non-vertical!) location line and the global Z axis.

Let's say the beam location line top two endpoints are stored in 'p' and 'q'. To determine the bottom points, we just need to know the height 'h' of the beam cross section and calculate a vector 'v' of length 'h' pointing downward and perpendicular to the beam location line. The desired points are given by p + v and q + v.

I used a similar calculation to determine the wall width or thickness vector 'w' to display the wall compound layers, except that it is horizontal, i.e. has a zero Z component, instead of lying in the plane P, with a minimal (negative) Z component.

Something like this untested snippet should do the job, given the beam location curve start point 'p', end point 'q' and height 'h' as defined above:

  XYZ u = q - p;
  XYZ w = XYZ.BasisZ.Cross( u );
  XYZ v = h * w.Cross( u ).Normalized;

As said, the desired points are then given by p + v and q + v.

Determine Hosted Family Host Type

On a different topic, in his latest AEC DevBlog post, Saikat Bhattacharya explains how you can determine the base host type of a hosted family via the Host parameter on the family document owner family property, which stores the following integer values corresponding to the FamilyHostingBehavior enumeration:

0. None
1. Wall
2. Floor
3. Ceiling
4. Roof
5. Face

The parameter value is zero, i.e. None, for families created using line and pattern based templates, so their host type cannot be determined using this method.

Note that if you have a face-based family instance, you can query its Host and HostFace properties to retrieve the host element and a reference to the hosting face, respectively.

Two more interesting methods to explore in this context are the FamilyCanConvertToFaceHostBased and ConvertFamilyToFaceHostBased methods provided by the FamilyUtils class.

Sweep PickPath Tolerance Criteria

Here is a rather specialised and hitherto undocumented topic of great importance to anyone trying to model precise complex swept geometry.

The issues below arose exploring the tolerance requirements of the 'Pick Path' options in the Revit UI, which map to the ReferenceArray and Reference input to the two FamilyItemFactory API calls for generating this kind of geometry:

Sweep NewSweep(
  bool isSolid,
  ReferenceArray path,
  SweepProfile profile,
  int profileLocationCurveIndex,
  ProfilePlaneLocation profilePlaneLocation );

SweptBlend NewSweptBlend(
  bool isSolid,
  Reference path,
  SweepProfile bottomProfile,
  SweepProfile topProfile );

It required quite a bit of research to resolve, both by the Revit development team and most of all by Bill Adkison of MarinCAD Custom Software Engineering, who is using this to create detailed furniture families like this:

Bill ran into a number of issues creating these very precise and detailed sweeps.

Here is an example of some of the ensuing discussions and results:

Question: I have problems with sweeps created via PickPath.

I am creating many successful pickpath sweeps. However, in some cases, pickpath sweeps are failing with a MemoryAccessViolation.

One example has two model lines which can each be selected to create a PickPath sweep, but when both are selected together, the sweep fails. I have confirmed that their endpoints meet up. One curve is a Hermite spline, the other a line. When I convert the spline to a set of line segments connecting the fit points, it works. What is the problem with connecting these two curves into a common sweep pattern? They fail interactively as well as via API. This is still basically a programming problem, because I need to know the criteria for when attaching splines and arcs will work. In another case of failure, a model line and a model arc of short radius: 0.34 inches, and included arc of .61 radians, so the ultimate arc length is .224 inches, well above the 1/32" Revit precision threshold. You can sweep these curves independently, but they do not sweep when picked together. In the debugger, their endpoints line up.

Answer: There is a small gap between the line and arc in the model that causes the problems for that sweep path. Such gaps should be avoided.

Other conditions to watch out for are curves that are nearly tangent, but not quite tangent, or arcs with very large radii that are nearly indistinguishable from lines.

Here are some internal observations which may help give an idea of what is going on:

1. CollectPath3dCurveGRefs complains about the gap between the line and arc in the model. The gap has size about 9.8e-6, but that function uses DOUBLE_EPS (= 1.0e-9) as a point-to-point tolerance. It issues a DBG_WARN but returns ERR_SUCCESS when it finds a gap.

The unit tangents of the line and arc at the point where they (nearly) meet differ by about 0.002 in the z-coordinate (and somewhat less than that in the y-coordinate). Apparently, Revit can bridge huge angles in lines, while being rather intolerant of even small angles in other areas.

CreateSweptSolid calls fixGapsInSweepPath, which calls trimCurvesToNbrs, but the latter function uses sqrt(0.1)*DOUBLE_EPS as a point-to-point tolerance, so it considers the gap to need "repair". It attempts to intersect the line and the arc, but that ultimately calls circXLine2d, which uses DOUBLE_EPS as a tolerance, so that function does not find an intersection. TrimCurvesToNbrs therefore does not modify the path (i.e., it does not "fix" the gap). It does check that the result is continuous to within a certain tolerance, but it uses the vertex tolerance for that check, and this gap is smaller than the vertex tolerance (which is about 0.0005).

CreateSweptSolid ultimately fails because getCornerTurningTrf fails when finding the corner-turning transform from the line to the arc, because vecAlmostEqual(cornerPnt1, cornerPnt2) is false. This essentially uses DOUBLE_EPS as a point-to-point tolerance. I confirmed that avoiding that rejection in the debugger allows the swept solid to be constructed successfully. Nevertheless, such gap and lack of tangency should be avoided whenever possible.

2. In the model, the line and the Hermite spline are not accurately tangent. Their tangent vectors at the point where the curves meet differ by about 0.01 in one of the coordinates; they meet at an angle of about 0.017 radians (= 1.02 degrees). While computing the mitre surface between the line and the spline, getMiterCurve then calls pathSegsAreNearlyTangent, but that uses a tolerance of one degree, so this case doesn't even meet the criterion for being nearly tangent. getMiterCurve then fails at the check for parallel normVec = (0.49, -0.85, 0.13) and planeNorm = (-0.86, -0.5, 0.0) (approximately).

PlaneNorm is the normal vector of the plane of the sweep path, as computed by getMiterCurve, while normVec was passed down from createSweepAlongCurve, where it was computed by a call to getRadii, which gets it directly from the sweep frame passed to createSweptSolid.

3. Please make the line accurately tangent to the spline in the example. They meet at an angle slightly greater than one degree.

Of course, making the line accurately tangent to the spline is a difficult numerical problem, and will involve modifying both curves, which are in different planes, which will also have to be modified. Alternatively, one could recognize the situation and either break the sweep, or go back to all line segments.

4. Please make analytic computations (i.e., those involving lines, arcs, planes, and other simple curves or surfaces as accurate as possible for double-precision floating-point computations. In such cases, values that would ideally be equal should be considerably less than 1.0e-9. In general, Revit expects points that are ideally coincident to have a distance considerably less than about 1/160". In some cases, though, Revit code demands a tighter tolerance. Curves that are ideally tangent should have an angle at most 0.1 degrees.

The failure to create a sweep for the line/spline path in the sample with a circular profile of radius about 0.4329 might be fixed by making the line tangent to the spline.

5. There seem to be a number of hardcoded almost vertical and almost unit vectors in your code.

Revit definitely does not like slightly off-axis lines and planes.

It will certainly help stability if you can replace all vectors like the following one by the almost identical ones aligned with the cardinal axes:

  XYZ normalizedMajorAxis 
    = new XYZ( 1.0,
      -0.00000000000024924835886401896,
      0.0000000000000012680828609390458 );

Specifying very slightly off-axis data is just asking for trouble. Do you really need to model anything that absolutely has to be so slightly off-axis? Is rounding an option for the input data you provide? This is not hard, once you are aware of the issue.

Response: 1. Details such as the point-to-point tolerance is exactly the kind of information I am looking for.

The gap in my data is a somewhat bigger than I expected, so I will write code to re-close them after my Revit computations are finished.

Does the fact that the tangents differ by this amount matter, i.e. cause the failure? Sweep handles 90-degree corners for line segments. Do non-lines have to have matching tangents? If so, that is great to know, as well as utterly unobvious. I can take evasive action if the tangents must match.

What is 'the vertex tolerance' exactly, in contrast to 'point to point'? For use by sweeps or path validation after the basic point to point? Is it used for Angles? Should I just be concerned with the DOUBLE_EPS distance for this problem?

2. So you require tangency for connecting PickPath segments that aren't lines? That is good to know. As noted earlier, because PickPath works with corners between lines, I assumed there was no tangent requirement for connecting elements, nor did I see any in the documentation. So to clarify the rules: must connecting PickPath elements have shared tangents at their connection point, UNLESS they are bound line segments? Here is the current list of possibilities:

• Line – Line: no tangency requirements.
• Line – Spline: tangency required.
• Line – Arc: tangent required or no?
• Spline – Arc: ?
• Spline – Spline: ?
• Spline – Arc: ?

If tangency requirements are a problem, I will correct them if possible, or revert to line segments.

I updated my logic to detect gaps and tangential inequality at connection points of multi-curve PickPaths, leading to the key logic summarised in the following code:

  /// <summary>
  /// Revit angle tolerance: 1 degree
  /// has been shown to be stable.
  /// </summary>
  const double kRevitAngleTolerance = Math.PI / 180.0;
 
  XYZ curCurveStartPt = null; // from current curve
  XYZ prevCurveEndPt = null; // from previous curve or null
  XYZ shiftVector = null;
 
  // Use DOUBLE_EPS tolerance in IsAlmostEqualTo 
  // for legitimate endpoint proximity.
 
  bool shiftCurve = ( prevCurveEndPt != null ) 
    && !curCurveStartPt.IsAlmostEqualTo( 
      prevCurveEndPt );
 
  if( shiftCurve )
  {
    // This case very rarely triggers.
 
    shiftVector = curCurveStartPt.Subtract( 
      prevCurveEndPt );
  }
 
  XYZ nextCurveStartTan = null; // from next curve or null
  bool nextCurveIsLine = null; // from next curve, if any
 
  XYZ curCurveEndTan = null; // from current curve
  bool curCurveIsLine = null; // from current curve
 
  double epsTanAngle = nextCurveStartTan.AngleTo( 
    curCurveEndTan );
 
  // Use cited tolerance of 1 degree between 
  // connecting endpoint tangent vectors. 
  // I actually experimented with up to 5 degrees, 
  // and although I observed cases of tangent 
  // differences of at least 2.6 degrees to
  // successfully sweep, sometimes it works and 
  // sometimes it excepts.
  // 1 degree has held up well so far; 
  // I have no known failures with it.
  // But the result is annoying notches in Revit 
  // in places where AutoCAD sweeps can handle 
  // the same curves automatically.
 
  bool writeSweepNow = false;
 
  if( ( nextCurveStartTan != null )
    // connecting lines have unequal 
    // tangents but work in Revit.
    && ( !curCurveIsLine || !nextCurveIsLine ) 
    && ( epsTanAngle > kRevitAngleTolerance ) )
  {
    // Break off sweep and start a new one;
    // when tangent angles exceed this, 
    // the sweep can except.
 
    // Final code to tweak current curve tangents 
    // would go here; this is a big project in itself.
 
    writeSweepNow = true;
  }
 
  // if (shiftCurve)
 
  // Current curve is re-read, with shift in 
  // location set in shiftVector.
  // Append current curve to model and record its 
  // references in current curve reference array.
 
  // if (writeSweepNow)
 
  // Sweep is written with current curve, and new 
  // Sweep begins with the next curve.
  // Loop until all curves are accumulated, 
  // then write final sweep.

This eliminates all the failures due to connecting multiple curves in PickPath sweep creation.

MEP Calculations

A second question was raised on another rather specialised calculation topic:

Question: Can you point to any documents describing the Revit MEP calculation methodology?

Answer: The MEP calculations are described in the Revit WikiHelp Reference.

You can also look at Martin Schmid's Autodesk University 2010 classes ME330-3 Calculations in Revit MEP, primarily focused on duct and pipe, and ME231-2 Categorically, Demand It on Your Schedule: You Con-Du-It in Revit MEP, with a focus on electrical calculation. The former includes a video recording.

The Hub Class

Saikat Bhattacharya published an article taking a look at the Revit API Hub class, never before mentioned here. It lives in the Autodesk.Revit.DB.Structure namespace and is derived from the base Element class. It represents a connection between two or more Revit Elements, avoiding the need to connect them with each other directly. They each refer to the hub, which manages all the connectivity information for them. Its interface is pretty minimal; the only members not inherited from Element appear to be:

• GetHubConnectorManager to retrieve the hub ConnectorManager.
• HasOrigin to indicate whether the hub has a specific location in 3D space.
• GetOrigin to retrieve the hub 3D position, if it has one.

Saikat presents a sample code snippet showing how to access the elements connected to a given hub.

Leaving the Unshaved

I shaved again, after a couple of weeks of abstinence. Here is a last parting shot before leaving the unshaved masses, and afterwards:

Note the prow of a boat sticking out of the wall in the left-hand picture... special bonus points for anyone who can tell where this photo was taken :-)

Wall Footing Relationship Revisited

In the far distant past, I looked at various ways to programmatically determine relationships between associated objects (also in VB), including references between a host object and its hosted dependent elements, e.g. determining the relationship between a wall and its footing.

That was back in the year 2009, using Revit 2010.

A few things have changed and been added since then, but the more things change, the more they stay the same, don't they?

Anyway, this very question was raised again:

Question: Is there a way to obtain a reference to a wall footing from the wall attached to it?

Answer: Yes, sure, there are several different possibilities to achieve this.

You could start off by determining the bottom face of the wall.

Using that, you could set up an ElementIntersectsSolidFilter for a filtered element collector to retrieve all foundation elements touching or intersecting that face, as described for retrieving all touching beams. You would obviously want to apply as many quick filters as possible before taking recourse to the slow geometric filtering, e.g. check for level, category, type, etc. first.

Another way to determine adjacency of Revit BIM elements is to make use of the ray casting functionality provided by the FindReferencesByDirection method, FindReferencesWithContextByDirection method and the ReferenceIntersector class, e.g. cast a ray downwards from the wall and detect the first foundation hit by it.

Last but not least, another way to determine relationships between associated objects such as a wall and its footing is to temporarily delete the host object, causing the dependent objects to be deleted as well. The deleted element ids can be determined, and the whole operation undone to leave the model unchanged.

I described this principle several times, e.g. looking at object relationships (in VB), and specifically determining the wall footing of a given wall.

I cannot tell off-hand which of these methods is most useful and efficient in your specific case, although I would be very interested in seeing the results of some comparisons and benchmarks evaluating this.

Anyway, I note that The Building Coder sample command CmdWallFooting implementing the latter approach is pretty much out of date, having been simply flat ported across several Revit API releases in the past few years.

I therefore updated it for and tested it with Revit 2013, and can now confirm that it still works.

Here is the updated implementation:

[Transaction( TransactionMode.Manual )]
class CmdWallFooting : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication app = commandData.Application;
    UIDocument uidoc = app.ActiveUIDocument;
    Document doc = uidoc.Document;
 
    Wall wall = Util.SelectSingleElementOfType(
      uidoc, typeof( Wall ), "a wall", false ) 
        as Wall;
 
    if ( null == wall )
    {
      message 
        = "Please select a single wall element.";
 
      return Result.Failed;
    }
 
    ICollection<ElementId> delIds = null;
 
    using( Transaction t = new Transaction( doc ) )
    {
      try
      {
        t.Start( "Temporary Wall Deletion" );
 
        delIds = doc.Delete( wall );
 
        t.RollBack();
      }
      catch ( Exception ex )
      {
        message = "Deletion failed: " + ex.Message;
        t.RollBack();
      }
    }
 
    ContFooting footing = null;
 
    foreach ( ElementId id in delIds )
    {
      footing = doc.GetElement( id ) as ContFooting;
 
      if( null != footing )
      {
        break;
      }
    }
 
    string s = Util.ElementDescription( wall );
 
    Util.InfoMsg( ( null == footing )
      ? string.Format( "No footing found for {0}.", s )
      : string.Format( "{0} has {1}.", s,
        Util.ElementDescription( footing ) ) );
 
    return Result.Succeeded;
  }
}

I ran this command on a minimal sample model containing just one structural wall with its footing:

The command reports the expected relationship:

It says:

Wall Walls <164432 Generic - 200mm> has 
ContFooting Structural Foundations <164470 
Retaining Footing - 300 x 600 x 300>.

Here is version 2013.0.99.3 of The Building Coder samples including the updated CmdWallFooting external command.

Element Intersection

A common question when analysing a BIM is determining whether any of its elements intersect.

This was actually surprisingly difficult to answer programmatically in Revit a few releases back, as some of the interesting uses of the FindReferencesByDirection method show, for example the FindColumns SDK sample. Later, that method was enhanced to lead to FindReferencesWithContextByDirection.

The FindColumns sample searches for intersections between walls and columns by shooting a ray along the wall centre line, raised above the bottom level by a foot or so, and detecting any columns hit by it. One obvious problem with this approach is its inaccuracy – any column just partially intersecting the wall may easily be missed by the ray.

A few years ago, that was the best an add-in developer could hope for, and things looked even worse before the advent of these methods.

So what is the situation today? In short:

Question: How can I programmatically detect whether two Revit elements intersect?

Answer: You can now perform a Boolean operation on Revit element solids and determine whether they intersect using the BooleanOperationsUtils class ExecuteBooleanOperation method.

Please note that the resulting intersection solid is transient, in-memory only. It can be used for calculation and short-term visualisation using the analysis visualisation framework AVF, but it cannot be added to the Revit database or made persistent.

This class was introduced in the Revit 2012 API, and the associated webcast showed it being used impressively in a much improved version of the FindColumns SDK sample. This version determines the exact intersection solids between all columns and walls instead of roughly approximating the intersection detection by casting a single ray, and displays them to the user through AVF.

The Boolean intersection demo is described in detail and the source can be downloaded from the discussion of a simpler derived sample using AVF to highlight rooms.

Another example of making use of this class is given by the GeometryCreation_BooleanOperation SDK sample.

Finally, here are two discussions on element intersection before the introduction of the BooleanOperationsUtils class, on intersection between elements in Revit 2011 and the InstanceVoidCutUtils class.

AEC Technology Update

If you are interested in a succinct summary of all the key developments in the AEC technology industry in the past couple of months, here is a potantial cancidate: the AEC Technology Updates, Fall 2012, including some snippets of Autodesk related news such as Revit LT and the Vela acquisition.

Room in Area Predicate via Point in Polygon Test

I presented a sample last week showing how to access area boundary loops and display the result graphically by creating corresponding model curves.

Jeroen van Vlierden of ICN Solutions BV took this idea one step further by combining the area boundary loop extraction with my point in polygon containment algorithm to find out whether a given room resides within an area.

He also pointed out that my area boundary sample attempts to use the Area class directly in a filtered element collector, which is not allowed, as I explained when accessing room data.

Jeroen explains:

I can now implement the point in polygon test.

Thank you very much for solving my problem. This will help me determine which rooms are part of which area and therefore also which windows belong to which area. It is part of a program in which we want to determine how many square meters glass is being used in user specified areas.

I implemented your point in polygon test as an extension method of the area element type. C# is such an elegant language ;-)

I use extension methods a lot to extend the Revit API with my own methods, especially when it comes to dealing with various kinds of parameters etc.

After using them for a while, I will not even remember they are not part of the official API.

The only thing that will not work correctly (yet) is when there is an arc part of the polygon.

One easy way to deal approximately with the arc (and all other non-linear segments as well) would be to make use of the Revit API geometric tessellation functionality, reducing everything to (approximate) straight line segments. This is extremely simple, since all curve elements implement the Tessellate method returning a list of XYZ approximation points. Its use is demonstrated in numerous places in the SDK samples.

I reused your code based on UV points by writing an extension method to convert XYZ to UV and I have added a constructor to the PointInPoly class that allows a List of XYZ points to define the PointInPoly class.

Here is my version of the point in polygon implementation PointInPoly.cs.

Here is the entire code of the various extension methods defined in the module PointInPolyExtensions.cs:

public static class PointInPolyExtensions
{
  /// <summary>
  /// Add new point to list, unless already present.
  /// </summary>
  private static void AddToPunten(
    List<XYZ> XYZarray,
    XYZ p1 )
  {
    var p = XYZarray.Where(
      c => Math.Abs( c.X - p1.X ) < 0.001
        && Math.Abs( c.Y - p1.Y ) < 0.001 )
      .FirstOrDefault();
 
    if( p == null )
    {
      XYZarray.Add( p1 );
    }
  }
 
  /// <summary>
  /// Return a list of boundary 
  /// points for the given room.
  /// </summary>
  private static List<XYZ> MaakPuntArray(
    Room room )
  {
    SpatialElementBoundaryOptions opt
      = new SpatialElementBoundaryOptions();
 
    opt.SpatialElementBoundaryLocation
      = SpatialElementBoundaryLocation.Center;
 
    var boundaries = room.GetBoundarySegments(
      opt );
 
    return MaakPuntArray( boundaries );
  }
 
  /// <summary>
  /// Return a list of boundary points 
  /// for the given boundary segments.
  /// </summary>
  private static List<XYZ> MaakPuntArray(
    IList<IList<BoundarySegment>> boundaries )
  {
    List<XYZ> puntArray = new List<XYZ>();
    foreach( var bl in boundaries )
    {
      foreach( var s in bl )
      {
        Curve c = s.Curve;
        AddToPunten( puntArray, c.get_EndPoint( 0 ) );
        AddToPunten( puntArray, c.get_EndPoint( 1 ) );
      }
    }
    puntArray.Add( puntArray.First() );
    return puntArray;
  }
 
  /// <summary>
  /// Return a list of boundary 
  /// points for the given area.
  /// </summary>
  private static List<XYZ> MaakPuntArray(
    Area area )
  {
    SpatialElementBoundaryOptions opt
      = new SpatialElementBoundaryOptions();
 
    opt.SpatialElementBoundaryLocation
      = SpatialElementBoundaryLocation.Center;
 
    var boundaries = area.GetBoundarySegments(
      opt );
 
    return MaakPuntArray( boundaries );
  }
 
  /// <summary>
  /// Check whether this area contains a given point.
  /// </summary>
  public static bool AreaContains( this Area a, XYZ p1 )
  {
    bool ret = false;
    var p = MaakPuntArray( a );
    PointInPoly pp = new PointInPoly();
    ret = pp.PolyGonContains( p, p1 );
    return ret;
  }
 
  /// <summary>
  /// Check whether this room contains a given point.
  /// </summary>
  public static bool RoomContains( this Room r, XYZ p1 )
  {
    bool ret = false;
    var p = MaakPuntArray( r );
    PointInPoly pp = new PointInPoly();
    ret = pp.PolyGonContains( p, p1 );
    return ret;
  }
 
  /// <summary>
  /// Project an XYZ point to a UV one in the 
  /// XY plane by simply dropping the Z coordinate.
  /// </summary>
  public static UV TOUV( this XYZ point )
  {
    UV ret = new UV( point.X, point.Y );
    return ret;
  }
}

Many thanks to Jeroen for this discussion and nice example!

For completeness' sake and your convenience, here is an updated version of the DisplayBoundary sample including

• The fix to filter for spatial elements instead of areas
• The point in polygon algorithm
• Jeroen's extension methods

Enjoy!

Connector Orientation

Today is the Pentecost or Whit Monday holiday in Neuchâtel, and I am in full tilt preparing for the AEC DevCamp in Waltham next week.

I will be presenting sessions on the new Revit 2013 UI API features, the Revit MEP API, and extensible storage.

I am of course looking forward much more to the many exciting other presentations by my colleagues in the ADN DevTech AEC team and especially by members of the Revit development team, directly from the horse's mouth, so to speak. Have a look at the session list and descriptions to see them all in their full glory.

Meanwhile, here is yet another MEP related topic to pick up:

Two years ago, I presented a solution for determining the width and height orientation of a Revit MEP connector.

Now Martin Schmid describes a new useful aspect of this issue which also leads to a very important point on real numbers comparisons.

Question: How do I determine the orientation of a connector in my project? From Revit Lookup, I can find where the information is, but I'm not sure how to interpret this without a 'visual'.

Answer: It was easy enough to determine by exporting a simple Revit model to AutoCAD, and displaying the coordinate entries there.

I thought I would share what I found to save other users from having to go through the same research.

For a FamilyInstance, such as a pipe fitting, the information can be found via

• FamilyInstance > MEPModel > ConnectorManager > ConnectorSet > Connector > CoordinateSystem

As the image below shows, the Z coordinate of CoordinateSystem indicates the normal direction of the connector. The CoordinateSystem.Origin is the actual location in the model:

For a MEPCurve such as a pipe, the access is slightly different:

• MEPCurve > ConnectorManager > ConnectorSet > Connector > CoordinateSystem

So, if you're trying to determine if two connectors are parallel and facing opposite directions, you can test that the Z axis vectors of the two connectors' CoordinateSystem properties pointing in exactly opposite directions, i.e. one equals the negation of the other.

Many thanks to Martin for this explanation!

Real Number Equality Testing

Jeremy adds: since the connector CoordinateSystem Z axis vector is an XYZ instance, i.e. a triple of three real numbers, comparing their equality leads back to a floating point number comparison.

In this case, you should actually almost never ever use an exact equality comparison such as Equals, or '=='.

You need to use an appropriate real number equality test instead.

Our guru GNU says: "we recommend that you consider not comparing real numbers for exact equality with the == operator, but rather check that real numbers are within an acceptable tolerance".

For the Revit API XYZ point and vector instances, this can easily be achieved by using the IsAlmostEqualTo method instead.

The comparison between the two connectors' CoordinateSystem Z axis vectors can therefore be implemented like this, for example:

  conn1.CoordinateSystem.BasisZ.IsAlmostEqualTo( 
    -conn2.CoordinateSystem.BasisZ );

I already discussed taking this one step further several times, for instance to implement the XyzEqualityComparer for retrieving unique geometry vertices, nested instance geometry, toposurface point classification and accessing the top faces ofa sloped wall.