The Building Coder

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.

Accessing and Filtering by Ramp Material

I had a chat with Ning Zhou, who was away from the Revit API for a while and is now happily back in the fold.

He explored how to access the material of a ramp element.

Access to Ramp Material

Question: Is there a way to get the ramp material information using API? I tried lots of paths and could not find anything.

Answer (by Ning himself): I searched again using RevitLookup snoop.

It turns out that basic material info is accessible after all. I found it us under 'Object type' instead of 'Parameters'. Apparently only the material name is stored there, in the built-in parameter 'RAMP_ATTR_MATERIAL':

I have not seen anything providing the material volume, so I guess I'll have to use the geometry access and calculate that myself instead.

At least I can now implement a filter selection using the material name!

  FilteredElementCollector concreteRamps
    = new FilteredElementCollector( doc )
      .WhereElementIsNotElementType()
      .OfCategory( BuiltInCategory.OST_Ramps )
      .Where( e =>
      {
        ElementId id = e.GetValidTypes().First(
          id2 => id2.Equals( e.GetTypeId() ) );
 
        Material m = doc.GetElement( doc.GetElement( id )
          .get_Parameter(
            BuiltInParameter.RAMP_ATTR_MATERIAL )
          .AsElementId() ) as Material;
 
        return m.Name.Contains( "Concrete" );
      } );

Many thanks to Ning for his research and sharing this helpful result.

Before closing, here is another useful pointer on family instance placement and rotation:

Rotate a Family in Three Different Axes

Here is a pretty neat article on family instance placement strategies from a user point of view, describing how to rotate a family in three different axes, which is certainly useful for developers as well.

As always in the Revit API, knowing the best practice from a user and product point of view is of paramount importance before putting any thoughts or efforts at all into API development issues.

Changing a Family Parameter from Type to Instance

Here is a short and simple question that just cropped up and required some digging around until my colleague Phil Xia came up with the right answer:

Question: Is it possible to change the type of a family parameter programmatically?

This is possible in the family editor.

I only see the IsInstance property, though, and it is read-only.

I could achieve the same effect by deleting the parameter and creating a new one. Obviously that would require updating all the existing values, though, if there are any, to change from the old parameter to the new one. I don't really see this as an option. Besides, the parameter could be referenced from other parameters.

Seeing that this is possible from within the family editor, I actually don’t see any need for this property to be read-only.

I don't think changing a family parameter from type to instance and vice versa should not be so hard.

Is there some other method that allows me to achieve this?

Answer: Yes, sure, you are lucky, and so are we all: the following two FamilyManager methods set the given family parameter to instance or type:

• MakeInstance – Set the family parameter as an instance parameter.
• MakeType – Set the family parameter as a type parameter.

I hope this will save you from repeating the same digging all over again :-)

Many thanks to Phil for explicitly pointing this out!

LoadFamily and Collector Iteration Performance

Since we are into the topic of family loading performance anyway, after yesterdays discussion on efficient sweep creation, here is another interesting discussion with some useful family loading and symbol filtering benchmarking results and observations by Thomas Jarzyna and an in-depth analysis of the effects of converting a filtered element collector to a .NET collection by Scott Conover:

Question: I need to load some family symbols into my project. I have a lot of different families and even more symbols, so to keep the projects small and clean I would prefer to load family symbols on demand only.

Therefore, whenever an instance of a family is to be created, I need to check first whether the family symbol is already loaded.

I can see two possible approaches to achieve this:

• Check whether the family symbol already exist by iterating through the database using a filtered element collector searching for family name and family symbol name.
• Not checking anything, and just always calling LoadFamilySymbol. It runs fine even if the family symbol is already loaded. One negative side effect of this approach is the "one time conversion" dialogue popping up for older families every time.

Which approach is better from a performance centred point of view, please?

Is there any other possible approach?

Answer: Both of your two approaches sound feasible.

I also find the "one time conversion" dialogue rather irritating and would not want my users to see it, especially not repeatedly.

If that is a serious problem for you, you could implement a system to ensure that it never occurs more than once. For instance, you could create different sub-directories for the different Revit versions of the same family, and check whether an updated version has already been generated before loading an older one.

However, I would expect the use of the filtered element collector to be much (very much!) more efficient.

However^2, it really depends on so many factors that it is impossible to say for sure.

The only way to really answer this with certainty for your particular system, workflow needs, and installation situation is to benchmark the different options.

I described a simple benchmarking system that I would use in a Revit add-in in lack of anything more sophisticated.

I cannot think of any other approach offhand.

The thought of calling LoadFamily without even checking beforehand actually never occurred to me :-)

Here are two different implementation examples checking whether a family has already been loaded, and loading it otherwise, for

• Creating and inserting an extrusion family
• Structural concrete setout points

I hope they fulfil your needs.

Response: Thank you for the answer.

I was hoping for a simple standard best practice, but I see it's not as easy as that.

In the meantime, I've done a little bit of benchmarking myself. Just basic, using a stopwatch:

And you are right, depending on the quantity of different Types (FamilySymbols) these approaches differ significantly.

For a scenario of creating 2000 family instances from one family (see attached sheet), this is my conclusion:

• If you expect less than a dozen different family symbols to load, just load them once via "LoadFamilySymbol" and don't care about iterating the element collection for the already loaded family symbols.
• Otherwise, iterating and finding the loaded family symbols first is better.
• Of course, this depends on the complexity of the family types and the environment (hardware & current load).
• A large number of different families is not considered yet.

I also noted the following interesting fact while iterating for "known" family symbols:

  var collector = new FilteredElementCollector( doc );

  IEnumerable<FamilySymbol> familySymbols = collector
    .OfClass( typeof( FamilySymbol ) )
    .ToElements()
    .OfType<FamilySymbol>();

The additional call to the ToElements method makes the search using the collector slightly less effective (some milliseconds slower) compared to:

  IEnumerable<FamilySymbol> familySymbols = collector
    .OfClass( typeof( FamilySymbol ) )
    .OfType<FamilySymbol>();

But in the long term, iterating over the family symbols is much faster when ToElements is called first.

For the 2000 instances it takes 14 seconds without ToElements vs. 9 seconds with.

I guess this has to do with the caching provided by possible multiple enumerations of IEnumerable.

What do you think?

Thank you, till next time.

Answer: Thank you for your very interesting results and observations, and congratulations on your first benchmarking results! They are already very interesting.

A call to ToElements definitely costs some performance, since it allocates an entirely new generic .NET collection and copies all the elements across from the Revit filtered element collector, as I mentioned discussing FindElement and collector optimisation.

I am surprised and interested (and was initially a little disappointed) to hear that the subsequent iteration over the .NET collection is measurably faster than the Revit collector, though.

Yes, the speed improvement is probably indeed related to the explanation you point to. In this case, the Revit element collector may be storing the elements in 'Revit memory' and eating cycles when marshalling them across to '.NET memory'. This marshalling effort may need to be performed anew on each repetition of the iteration.

Ah yes, with that explanation, I am perfectly happy with this observation, and not disappointed at all.

Thank you for these illuminating results.

Scott adds: I would expect the total time spent in FilteredElementCollector.ToElements and subsequent iteration to be longer than direct iteration of FilteredElementCollector, regardless of the number of elements that pass the filter.

Of course, once ToElements has run and you store the managed handles, iteration of this collection should be fast – you are not going back to the document to find the elements again or filter them or wrap them in managed handles.

If you are doing more than one iteration of a given filter criteria, the first one will always be faster than the second – because of the extra time taken to create the Elements collection. The other activities – traversing the database, applying and evaluating the filter, wrapping the elements that pass into managed code – happen on both.

If you know you need to have the same filtered set of elements more than once, saving them in the collection should be faster for the second and subsequent iterations. This assumes that you know the document hasn’t changed where there are new elements that pass the filter (or some of them are deleted). The second iteration over the managed collection should be faster than re-traversing the document. This is a pretty specialized approach. The other reasons for converting FilteredElementCollector to a collection (you want to store a list of elements or ids for later, you need such a list as input to another method, you want to delete anything you find, etc.) still apply.

If you are running multiple loops on the collector with no changes in between, the second will be consistently faster. Optimally, you might want to unroll the loop to just do everything in one shot.

The first might be faster than the second if the collector is returning a really large number of elements.

Mostly, you want to get a set of things once and just do things to it once. Normally, only certain specialized applications such as multiple data extractions or multiple permutations for design studies might require retrieval of the exact same data and then doing things to it repeatedly in the same code sequence.

Let’s use made up concrete numbers.

• It takes 100 ms to process the model and find elements that pass the filters, and to wrap each element into the API object.
• It takes 5 ms to build the .NET collection returned by ToElements.
• It takes 1 ms to traverse a .NET IEnumerable<Element>, which could be either the Revit collector or the .NET collection.

So with one group of elements processed once:

• With collection: 100 + 5 + 1 = 106 ms.
• Without collection: 100 + 1 = 101 ms.

With the same exact group of elements processed 10 times in the same code (where we know there is no chance new elements were added or elements deleted that we care about):

• With collection obtained once: 100 + 5 + 10 * 1 = 116 ms.
• Without collection: 100 * 10 + 10 * 1 = 1010 ms.

Make sense?

The key thing to understand is that FilteredElementCollector caches nothing (except the filters applied to it, of course). Caching data needed for multiple things will be better – always – but premature if there’s no need to have such a cache at all.

Note that the built-in collections on Document (.WallTypes, etc.) – which are becoming obsolete in future versions – use FilteredElementCollector as their base; there is no caching done there either, and no real advantage to them other than saving the coding effort of building the collector and filters.

Sweep Family Performance Enhancement

Now I am back at work again, enjoying the queries coming in from developers, postponing other important things such as my own long-term class and presentation preparations etc. Addicted to helping, that's me.

Anyway, here is a piece of doubly good news, in that the developers mentioned below did a good job of helping themselves, in addition to achieving a radical speed improvement from 40 hours down to 3 minutes, i.e. just 0.125% of the original time, to programmatically generate some Revit families.

Question: The problem was initially reported by Hu Zhao in a recent comment:

I have 80,000 elements to generate, now I use sweep; do you know which is faster of sweep and extrusion? Which can offer a better performance for the computer?

It took 40 hours for the sweep operations.

Is it possible to accelerate this?

In Rhino script, only 10 minutes is enough for this operation.

Hu's colleague and Revit API blogger David Tan clarifies:

Zhao's scenario is to create about 80,000 sweeps in Revit in one shot. Per his test, it will take about 20 hours, while his workmate can achieve it in Rhino within 10 minutes. Zhao expects that Revit could do faster.

As Zhao's test was done in an open family document (with UIDocument), I tried to use in-memory document but it still take about 18 hours to draw all 80K sweeps.

Zhao noticed that although all the drawing work is done in a single transaction, it seems that Revit tries to regenerate the document after there are sweeps created already automatically. We did set the RegenerationOption to be Manual. We say it because we saw Revit progress bar in the bottom-left corner indicates it.

Our questions:

1. Can we prohibit Revit's automatic regeneration?
2. More straightly, do we have any approach to get the job done faster?

Thanks a lot! And Happy Chinese Snake Year!

Answer: There may be a stray regeneration happening in sweep creation.

If you can demonstrate that (with a sample that creates something less than 80,000 sweeps, please :-), please provide a reproducible case for further analysis.

It is also worth asking what the use case is for 80,000 sweeps in one family. Are you possibly modelling things so detailed that that a building model with multiple instances of this will have performance problems?

Maybe you could add an image of what you are creating to motivate the development team by helping them understand.

Response: Here is an image showing what we are trying to achieve:

Each sweep corresponds to a single wooden roof in the image.

Here is also Hu Zhao's source code. We used an in-memory document and added a StopWatch to measure the time consumed.

The source code implements an external command in Program.cs. It will pop up a window and let you select a XML file, which contains creation data of all the sweeps. You can find the XML file along with the .sln file. To make things simple, I only put 2000+ sweeps creation data in the XML file.

Finally I want to share the good news from Hu Zhao. He resolved the performance problem by splitting all sweeps into 24 families and then combining them together. It only takes 3 minutes now. Of course, the cost is the reduced granularity; the model now no longer has individual roofs with embedded family instances. But as he is OK with it, we can say we have found the solution.

Hu added the following more detailed project description:

I am now working in a project plan team for the design of Arch_Tec_Lab in ETH Zürich (youtube link).

The parametric roof is generated in Rhino by my colleague, and the wooden beams will be assembled by robotic arms.

Before I joined this team, they imported the roof (including roof wooden structure) in DWG format, which did not display correctly in some plan and section views. In 3D view, it led to Revit crash because of too many triangle meshes in this imported format.

So I wrote a plugin to import the wooden beams (around 80k) of the roof.

We choose XML to exchange the position information, and I choose sweep instead of extrusion to generate each beam.

For now, the roof structure is divided into 7 parts of XML, which generates 7 families. It took me about 20 hours by using 3 dell precision computers.

Because the roof will be modified several times in the following days, I am now searching for a way to reduce the generation time.

I found that the speed of sweep is slower when the amount increased, and the regeneration that I cannot avoid is especially slow when the amount is above 1500.

Yesterday I found a way to accelerate the generation greatly.

I did like this: divided each 1 part into 24 pieces sections with the mark in XML, then generate each section into single family, and then combine them into a major family. These actions are all made by the plugin.

This is much more quicker.

Let me introduce our project once again.

The Arch_Tec_Lab is a role model project of department of Architecture, ETH Zürich. The team includes most important professors in the Institute of Technology in Architecture. The project aims to realize the BIM control in the life circle. Now we are using Revit to an extremely detail, and we enjoy the cloud rendering in Autodesk 360, except we wish it would also support animation rendering. Now we are working on the construction drawings in Revit.

In Switzerland, few architects use Autodesk products, because of the majority of the MAC users. But we want build a model for the architects and the students in department.

Many thanks to David and Hu for their research and sharing this remarkable performance enhancement!

Addendum: For completeness' sake, here is the slow source code and the complete fast solution. Hu clarifies: the code we posted yesterday is the slow version. The 'slow source code' shows how it works. The 'complete fast solution' is the quicker version.

There are 8 parts to generate. I finished all the work above in 20 hours using 3 computers, and now I can generate the smallest part in 3 minutes. Actually, the bigger part took about 6 hours by the slow method, and now takes about 50 minutes.

The time depends on how many parts I separate. I never test all the 80000 sweeps in one run, maybe it will cost one month ~:D – because the speed runs slower when time goes.

Adjustable Versus Perpendicular Spud

I recently presented an explanation of some Revit MEP family editor part type classes, which led to a follow-up:

Question: Thank you for the detailed answer about the duct fittings. I have a similar problem with one of the pipe fittings, namely spud. I know what a spud is, but not the difference between an adjustable and a perpendicular one.

Can you explain the actual difference, please?

Here is an image with some different spuds that I collected:

Answer: Spuds are analogous to taps in ductwork, which also have adjustable and perpendicular part types.

Their difference is probably best described by example. Here are two smaller branches, both routed from the larger main at 45 degrees:

The adjustable tap on the left adjusted to accommodate the 45-degree route.

The perpendicular tap on the right is constrained to tap perpendicularly off the main. Then, an elbow is automatically inserted after a short duct length to route the branch to the picked point.

Many thanks to Martin Schmid for this explanation.

Content Localisation

How to manage families and content creation is a crucial topic for a large number of Revit add-ins.

Brian Johnson, technical specialist on structural engineering solutions at Autodesk in Austin, Texas, discusses how to efficiently address some important aspects of this below.

First, however, let me wish everybody a Happy New Year of the Snake!

A year for reflection, planning and searching answers. A good time for shrewd dealings, political affairs and coups d'état. People will be more likely to scheme and ponder over matters before acting on them. An auspicious year for commerce and industry.

Let's hope so, indeed, and return to the issue of content localisation:

Content Localisation

Question: We have a large number of library items that we would like to work with in Revit, and they are used in many different countries and languages.

How can we manage this efficiently, please?

We would like to avoid duplicating any of the content, of course.

The differences include things like product name, description, part code, cost, and many other properties.

As far as I see, a Revit family cannot hold different values for a single property such as the item description.

What are your advice and the best practice for creating and maintaining a Revit family library for thousands of items and numerous languages?

Answer: Just as you say, Revit is not equipped to localise parameter names and types nor family names themselves.

Some level of automation will probably help significantly to solve or at least simplify this task.

A proof-of-concept for generating content from data and organizing content can be found in the Content Generator Extension available from the Autodesk Subscription centre. Note that all the Revit Extensions are bundled into a single download:

The content generator is intended for structural content from around the world using the section and material libraries (XML files) that also form the libraries for Robot Structural Analysis Professional and AutoCAD Structural Detailing:

I describe some of the inner workings of the Content Generator on pages 7-9 in the hand-out of my Autodesk University 2012 course SE3904 – Linking Revit Structure and Robot Structural Analysis: Beyond the Basics. For your convenience as a valued reader of The Building Coder, here is a direct download link.

I suggest installing the Extensions and trying it out. Your version of this might pull country specific data from your libraries/databases and generate a specific element for a specific language.

When considering creating your own custom families, my suggestion is to create the content with the best-suited family. If you use a specialised category like Structural Framing, you will get built-in parameters and behaviours that you may or may not want. The Generic Model set of family templates is the most basic and may be the most appropriate. I suggest populating the Identity Data and creating Shared Parameters for each family type and use those to filter, sort, and group the Schedule views in Revit.

As always, it is of utmost importance to discuss your plans with some of your Revit users and to get some training on how things are done in the typical workflows in Revit. This will help you understand what can be done with Revit out-of-the-box and what parts might use more automation.

Thank you, Brian, for the valuable advice!

MEP Family Editor Part Type Classes

While we are talking about content creation, here is another MEP specific question on the different classes of fitting types:

Question: I would like to know the definition for some of the part types of the fittings in the family editor.

Simple classes of fitting types like cap, cross, elbow, multiport, tap, transition, tee and union is clear, but I am uncertain about the more complex and less clear-cut parts.

Could you please clarify the following?

1. What is the difference between wye and pants?
2. Lateral tee and lateral cross are probably tees with an angle other than 90 degrees. They can also be rounded. Is this correct?
3. Offset is probably a kind of S-bend. Is this correct? Are eccentric transitions also included in this group?

Answer: Sure:

1. What is the difference between wye and pants?

It is no difference between creating wye and pants families. We just choose a part type that is close to the family name, which will makes sense if users check the part type.

Examples for wye:

Examples for pants:

2. Lateral tee and lateral cross are probably tees with an angle other than 90 degrees. They can also be rounded. Is this correct?

Again, lateral tee and lateral cross are used when the family name has similar words. The rule for using 'Lateral tee', 'Lateral cross' and 'Wye' is that the branch angle will be fixed when using the family in the project, so if the branch pipe has a different angle with the fitting, an elbow will be automatically added. If the part type is 'tee' or 'cross', the fitting will have a flexible angle branch itself.

Examples for lateral tee:

Example for lateral cross:

Lateral tee and lateral cross are also used as part types for pipe fittings, so they can be round as well.

3. Offset is probably a kind of S-bend. Is this correct? Are eccentric transitions also included in this group?

Examples for offset:

An eccentric transition should use the 'Transition' part type.

Family Symbols versus Types and SelectionFilterElement

Here is a question that has been asked a couple of times recently and thus seems worthwhile clarifying:

Question: If I access the OwnerFamily.Symbols in a family document, i.e. an RFA file, it returns an empty collection. If I load that same family into a project and access the Family.Symbols property, it returns the correct expected family types. Why does this property not work in the family editor?

Put differently, the following code snippet will show zero in the message box:

  Document fdoc = app.OpenDocumentFile(
    "C:/Family.rfa" );

  Family fam = fdoc.OwnerFamily;

  MessageBox.Show(fam.Symbols.Size.ToString());

Loading the same family into a project and then querying the symbol count returns the correct number:

  Document doc = app.OpenDocumentFile(
    "C:/Project.rvt" );

  Family fam = null;

  doc.LoadFamily( "C:/Family.rfa",
    new FamilyOption(), out fam );

  MessageBox.Show(fam.Symbols.Size.ToString());

Again, why does the Family.Symbols property not work in the family context?

Answer: Why things are the way they are is often quite difficult to answer. For that situation, I quite like the adage "Mine is not to wonder why, mine is but to do or die."

However, if I am allowed to rephrase you question constructively and ask "How can I access the symbols defined by a family in the family editor context?", the answer is clear and easy:

Use the FamilyManager class. The family manager object is used to manage the family types and parameters within a family document. You can access it through the Document.FamilyManager property on the family document object.

Getting back to the why and wherefore, it is helpful to understand that the family does not contain any symbols. It only contains types. The types can be compared to records in a database. The family parameters define the database fields, i.e. columns, and the types represent the records, i.e. rows. You could go even further and compare the individual family parameters with the database fields.

The symbols do not exist in the RFA. They only spring into existence when the family is loaded into a project.

Here is a slightly more detailed explanation:

Family types and symbols are completely different objects with different purposes.

There can be FamilySymbols in a family document. If so, these are the symbols defined by other families that are loaded into the document.

Family types live in the family where they are defined, whereas family symbols in a family always come from some other family loaded into it.

• Types can add parameters, formulas, etc. Symbols are limited to the definition in the source family.
• Types can be added and deleted at run time. Symbols cannot, other than by special operations like Duplicate.
• Symbols can be instantiated in the document they live in. Types cannot.

The FamilyType class in a family is not inherited from the Revit Element class, so types are not elements. It offers the ability to access parameters either for read or write in conjunction with the FamilyManager.

For certain operations in a family, such as getting an image from a type, you can set the type to be active using the FamilyManager.CurrentType property, then generate an image from a view of the family using the Document.Export method and an appropriate ImageExportOptions argument.

SelectionFilterElement

Two posts of Harry Mattison's on the SelectionFilterElement introduced in the Revit 2013 API just caught my attention and also seem worthwhile pointing out here.

The SelectionFilterElement is a filter element that stores an explicit list of ElementIds. Only elements whose ElementIds are contained in this list will pass the filter.

I mentioned the existence of this class briefly and rather cryptically in the initial overview of the Revit 2013 API.

Harry now presents two running snippets of sample code using a SelectionFilterElement to save a set of elements and subsequently retrieve and highlight them.

Definitely worth keeping in mind if you have a specific set of elements that you wish to access quickly.

Dynamo and Vasari Holiday Hacking

If the above is not enough for you, here is an invitation to venture further afield, into the realm of the Dynamo visual programming add-in for Revit:

• Dynamo holiday project overview
• Dynamic Relaxation via Dynamo
• Youtube video of results

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!

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 :-)

Create Dimension between Two Lines

Another one of those recurring questions: how to create dimensioning.

I took the opportunity to highlight how to search the samples, find a solution, and apply a correction to RevitLookup yourself.

You have the code.

May the Force be with you.

Question: I tried to create detail drawings programmatically using the ItemFactoryBase NewDimension method.

I am creating detail lines in the drafting view based the on the geometry wall elements and would like to use Revit dimensioning to insert measurements into the detail drawings.

How do I obtain the reference for the detail lines of a drafting view to be able to call the NewDimension method?

I am sure that this is possible, since I can create dimension lines in a drafting view using the dimension line commands on the Annotate ribbon.

Answer: Whenever you are faced with a question like this, please always begin by studying the three main official sources of information:

• The Revit API help file RevitAPI.chm.
• The online wikihelp Revit API Developer's Guide.
• The Revit SDK sample source code.

Normally, when researching an issue like this myself, I perform a global search across the entire project in the SDKSamples2013.sln solution.

This time, happily, I extended it to the entire samples directory instead, including RevitLookup. To tell the truth, I even searched my whole hard disk for all C# files containing NewDimension, because there were not that many in total.

This turned up the following hits in the Revit SDK folder (copy and paste to an editor to see the truncated lines):

C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1255):               //        m_revitApp.ActiveUIDocument.Document.Create.NewDimension(dimension.View, line, dimension.References, dimension.DimensionType);
C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1470):            m_revitApp.ActiveUIDocument.Document.Create.NewDimension(m_revitApp.ActiveUIDocument.Document.ActiveView,
C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1475):            m_revitApp.ActiveUIDocument.Document.FamilyCreate.NewDimension(m_revitApp.ActiveUIDocument.Document.ActiveView,
C:\...\SDK\RevitLookup\CS\Utils\Elements.cs(272):            Dimension dimensionClone = app.ActiveUIDocument.Document.Create.NewDimension(dimension.View, line, dimension.References);
C:\...\SDK\Samples\CreateDimensions\CS\Command.cs(213):                    Dimension newDimension = doc.Create.NewDimension(
C:\...\SDK\Samples\CreateDimensions\CS\Command1.cs(219):                    Dimension newDimension = doc.Create.NewDimension(
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(31):    /// The class allows users to create dimension using Document.FamilyCreate.NewDimension() function
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(91):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(125):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(160):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);

The very first of those, in the RevitLookup test framework, looks like it should answer your question right away:

  XYZ location1 = GeomUtils.kOrigin;
  XYZ location2 = new XYZ( 20.0, 0.0, 0.0 );
  XYZ location3 = new XYZ( 0.0, 20.0, 0.0 );
  XYZ location4 = new XYZ( 20.0, 20.0, 0.0 );
 
  Curve curve1 = m_revitApp.Application.Create
    .NewLine( location1, location2, true );
 
  Curve curve2 = m_revitApp.Application.Create
    .NewLine( location3, location4, true );
 
  DetailCurve dCurve1 = null;
  DetailCurve dCurve2 = null;
 
  if( !doc.IsFamilyDocument )
  {
    dCurve1 = doc.Create.NewDetailCurve(
      doc.ActiveView, curve1 );
 
    dCurve2 = doc.Create.NewDetailCurve(
      doc.ActiveView, curve2 );
  }
  else
  {
    if( null != doc.OwnerFamily
      && null != doc.OwnerFamily.FamilyCategory )
    {
      if( !doc.OwnerFamily.FamilyCategory.Name
        .Contains( "Detail" ) )
      {
        MessageBox.Show(
          "Please make sure you open a detail based family template.",
          "RevitLookup", MessageBoxButtons.OK,
          MessageBoxIcon.Information );
 
        return;
      }
    }
    dCurve1 = doc.FamilyCreate.NewDetailCurve(
      doc.ActiveView, curve1 );
 
    dCurve2 = doc.FamilyCreate.NewDetailCurve(
      doc.ActiveView, curve2 );
  }
 
  Line line = m_revitApp.Application.Create.NewLine(
    location2, location4, true );
 
  ReferenceArray refArray = new ReferenceArray();
 
  refArray.Append( dCurve1.GeometryCurve.Reference );
  refArray.Append( dCurve2.GeometryCurve.Reference );
 
  if( !doc.IsFamilyDocument )
  {
    doc.Create.NewDimension( 
      doc.ActiveView, line, refArray );
  }
  else
  {
    doc.FamilyCreate.NewDimension( 
      doc.ActiveView, line, refArray );
  }

I tried running this sample command by selecting the ribbon tab Add-Ins > Revit Lookup > Test Framework... > Object Hierarchy > APIObject > Element > Dimension > OK.

That calls the DimensionHardWired method to do the job.

Unfortunately, it throws an exception saying "Attempt to modify the model outside of transaction".

I fixed it by adding the following lines right at the beginning of the method:

  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "DimensionHardWired" );

Obviously, I need to commit the transaction and close the using statement at the end again:

    tx.Commit();
  }

Now is successfully completes with the following result:

You can also look at two The Building Coder samples creating wall dimensioning, either by iterating over the wall faces to pick the two suitable ones, or using FindReferencesByDirection to shoot a ray and find them directly.

They both retrieve the geometry references from the wall faces, and not from a simple detail line, though.

All together, this should provide more than enough to solve your issue.

Accessing the Path of a Family Document from the Family Instance

Before closing, here is pointer to a cool discovery by Saikat Bhattacharya: if you try to find the family document of a family instance and go through the path family instance > family symbol > family > document, you end up at the document containing the family instance. If you are actually after the family document defining the instance, you need to go through the EditFamily method instead. More details on accessing the path of a family document from an instance.

FamilyParameter IsShared Property

A long time ago, we discussed a workaround to access the shared family parameter GUID using reflection, more specifically (and obviously) .NET Reflection. If you are new to this, here is an in-depth Code Project article on Reflection in .NET.

Now Victor Chekalin, or Виктор Чекалин, ran into this issue as well and presents a much improved solution.

Here is the background and our discussion on this:

Question: Why does the FamilyParameter class have no IsShared Property, like the Parameter class does? I need to get list of all FamilyParameters and all their properties, including GUID.

Now, if I call the GUID property on a FamilyParameter that is not shared, Revit throws an InvalidOperationException. The only way I can check whether the FamilyParameter is shared or not is try to get GUID property and handle the exception if it is not shared.

This is a problem, because intercepting the exception takes a lot of time, and if a family has a lot of FamilyParameters, the program freezes significantly.

Why did the API developers implement this odd behaviour and not add an IsShared property to the FamilyParameter? Alternatively, they could just return null if the FamilyParameter is not shared.

Answer: Sorry about that.

These properties can be accessed using .NET Reflection.

Response: Yes, that looks as if it would help me.

I looked at RevitAPI.dll using Reflector and find it harder still to understand why the API developers didn't add the IsShared property to the FamilyParameter class. It is just a wrapper for the Parameter class, and it would just take one or two lines of code, e.g.

  public bool IsShared
  {
    get { return getParameter().IsShared; }
  }

Re-examining your post, though, maybe I understand after all: the GUID and IsShared properties were only added to the Parameter class in the Revit 2011 API. I guess that it was simply an oversight and they forgot add the new properties to the FamilyParameters as well. Maybe I'm wrong.

I hope this property is added in the future versions of the Revit API. As I can see from the post comments, I am not the only one wanting to see an IsShared property.

Implementing a FamilyParameter IsShared Extension Method

Based on your sample in the post, I wrote a simple extension method:

  public static bool IsShared( 
    this FamilyParameter familyParameter )
  {
    MethodInfo mi = familyParameter
      .GetType()
      .GetMethod( "getParameter", 
        BindingFlags.Instance 
        | BindingFlags.NonPublic );
 
    if( null == mi )
    {
      throw new InvalidOperationException( 
        "Could not find getParameter method" );
    }
 
    var parameter = mi.Invoke( familyParameter, 
      new object[] { } ) as Parameter;
 
    return parameter.IsShared;
  }

I used the internal getParameter method instead the m_Parameter field, because it is not recommended to use fields from other classes. Also, the getParameter method is used in most of the code that I saw in Reflector, not the m_Parameter field.

Using the FamilyParameter IsShared Extension Method

The use of the new method is completely obvious:

  foreach( FamilyParameter fp in mgr.Parameters )
  {
    if( fp.IsShared() )
    {
      familyTypeParameter.Guid = fp.GUID;
    }
  }

It works much faster than triggering and catching the exception, e.g.

  try { var guid = parameter.GUID; } 
  catch() {}

Thank you again for reminding me about reflection.

Answer: Many thanks to you, Victor, for your analysis, clean implementation, and sharing this with us!

Here is an updated version 2013.0.99.2 of The Building Coder samples including the extension method and a test call to it in the CmdFamilyParamGuid external command.

Elbow Fitting Selection and Dimensioning

Vacation time is approaching fast for me and lots of things need finishing off beforehand.

Meanwhile, one thing that had a number of developers champing at their bits for a while now finally came to fruition:

Autodesk Exchange

The Autodesk Exchange store is now open for application submissions. Stephen Preston already published several articles exaplaining the full details:

• Summary information
• Information for Revit developers
• Publishing an app

Here is another topic that recently kept me busy, with some helpful input from Martin Schmid and Steve Mycynek:

Selecting a Pipe Elbow Fitting

Question: I need to set the diameter of a pipe elbow fitting programmatically. The elbow diameter obviously needs to be adapted to the pipe diameter. The two pipes may also have different diameters.

I tried using the NewElbowFitting method to insert the elbow and simply pass in the two pipe connectors to it like this:

  doc.Create.NewElbowFitting( con1, con2 );

This does successfully create an elbow fitting instance. However, I don't see how to control which elbow symbol is inserted by this method. Is there any way to influence this?

Answer: Calling the NewElbowFitting method is similar to using the Trim tool in the user interface. When this method is called, Revit automatically chooses the appropriate elbow for you.

In Revit 2013, you can control the selection process through the routing preferences, whereas previous versions only enabled you to define one single default elbow, tee, etc. The routing preferences support multiple settings for different materials and sizes.

The routing preferences API is demonstrated by the RoutingPreferenceTools SDK sample. It implements three commands, one for analysis and reporting purposes, two for importing and exporting routing preferences to XML:

• Routing Preference Analysis: Analyze the routing preferences of a given pipe type to check for common problems, using the routing preferences API to look at all rules and criteria for a given PipeType.
• Routing Preference Builder with its two commands CommandReadPreferences and CommandWritePreferences: Set pipe type, fitting, and routing preferences in a project from data in an XML file and export these preferences to XML for archival, documentation, and collaboration purposes, allowing a user to work with routing preference data in a shareable XML format suitable for reuse in a wide variety of BIM management environments.

When you call NewElbowFitting, it inspects the pipe type and finds the first elbow in the appropriate routing preferences.

If the elbow inlet and outlet sizes differ, you need a reducing elbow.

How to Use the Routing Preferences API to Set the Elbow Symbol

The NewElbowFitting method will insert the elbow symbol specified in the routing preferences. Please note that while RP will choose the first symbol in the rule list that matches its criteria, you can always programmatically either set size criteria to ensure a later symbol is chosen for a given scenario, or re-order the rules using RoutingPreferenceManager RemoveRule and AddRule methods, at least temporarily, to force RP to choose a different elbow symbol than normal.

For example, if you have defined routing preference for 'Elbow Reducing - Threaded - MI - Class 150.rfa' and call this method, you will get an elbow that has different connection sizes as shown below on the left. If you don't have a transitioning elbow, but you do have a reducer defined, you will get a result as below right. Note that the reducer is quite odd in this particular model file :-)

In this case, both the Reducing Elbow and the Elbow + Reducer 'work'; which is used depends on their order in the definition of the RP.

The RP is the only way to influence this selection, both in the UI and in the API.

I Beg to Differ

In some cases, the outer diameter of the fitting and the pipes may differ. This is a content issue. Pipes and fittings are selected and connected based on the pipe 'Nominal Diameter' and the 'Nominal Diameter' of the fitting connector. In the Pipe Settings, a user can make the 'outer diameter' of a pipe bigger or smaller than its nominal diameter.

Here is an example with the following pipe type properties:

• Diameter 18 mm
• Outer Diameter 18 mm
• Inner Diameter 16 mm
• Size 18 mm

The generic pipe elbow fitting connected to the pipes by calling the NewElbowFitting method has the following properties:

• Nominal Diameter 18 mm
• Size 18 mm - 18 mm

For a fitting, the geometry of the elbow is completely arbitrary.

If you would like the elbow and pipe to have the same outer diameter, there are two ways to achieve this:

1. Make the outer diameter of the pipes bigger.
2. Modify the geometry of the elbow to be smaller.

Welded pipe fittings, for example, would have the same outer diameter, whereas threaded fittings, PVC, and others, typically have a larger outer diameter than the pipe itself, because the pipe engages into the fitting.

Change Elbow Dimension

Saikat handled an independent but related case that also happened to catch my attention:

Question: How can I change the diameter of an elbow pipe fitting, depending on the pipe diameter?

Answer by Saikat Bhattacharya: To test this, I created a pipe with an elbow fitting attached at one end. In the user interface, you can see that the nominal diameter parameter of the pipe is disabled, i.e. greyed out. The only thing I can do interactively in the user interface is modify the Nominal Radius of the pipe.

Based on this observation, I wrote the following few lines of code to modify the Nominal Radius of the selected elbow fitting using the API and it worked well:

  UIApplication uiApp = commandData.Application;
  UIDocument uiDoc = uiApp.ActiveUIDocument;
  Document doc = uiDoc.Document;
 
  Transaction trans = new Transaction( doc );
  trans.Start( "Change Diameter" );
  foreach( Element e in uiDoc.Selection.Elements )
  {
    FamilyInstance i = e as FamilyInstance;
 
    Parameter p = i.get_Parameter( 
      "Nominal Radius" );
 
    p.Set( 10 * 0.08333 );
  }
  trans.Commit();

For the complete solution and additional background information, please refer to Saikat's article on changing the diameter of an elbow fitting.

Invoke External Command on Start-up

Finally, to wrap this up, a little note on another issue that also cropped up and really is completely unrelated :-)

Question: I would like to call my Revit add-in in a batch operation in order to process multiple Revit files. The process would involve starting Revit, loading a model, invoking my add-in, and shutting down the application afterwards. I don't see any obvious command line option to achieve this. Is it possible at all?

Answer: Yes. This can be easily addressed by creating an external application, implementing appropriate OnStartup and DocumentOpened events, and driving the whole thing through a journal file or even directly from the command line.

AEC DevCamp 2012 Material

Both the AEC and Manufacturing DevCamp 2012 material is now publicly available.

The top-level node provides access to the overviews and the five main tracks, i.e.

• Revit Beginner
• Revit Advanced
• Infrastructure
• Cloud/Mobile and Other
• Business

For completeness' sake, here is the list of are the Revit beginner sessions:

These are the Revit advanced topics:

I presented some details from a number of the advanced Revit API session in my reports from DevCamp day one and DevCamp day two.

In conjunction with the getting started material available from the Revit developer centre, this material just about touches on all important aspects of the Revit API.

Please note that the material is still not completely finalised. Some items will still be updated. The location specified above is only temporary and will change, so don't use it for any long-term links, or be ready to update thm once the final archival location is in place.

Addendum: Here is a pointer to the finalised AEC DevCamp 2012 material download.

ARCxl Detail Library

I am normally not very concerned about Revit content, although that aspect is often of equal or greater importance than the API.

Here is a little item that happened to catch my attention anyway:

A library of non-proprietary generic construction details containing over 120,000 entries in native Revit, DWG and PDF file formats is now publicly available. It was built in 2008-2009 to an agreed set of standards within a single office, providing consistency throughout. The library also includes over 1,000 Revit components to modify the details. Being provided in RFA, RFT and DWG format, the details and components can easily be modified.

Family Instance Element Coordinate System

I spent last weekend in Sweden for my 35 year school anniversary, having graduated from the German school in Stockholm in May 1977.

The day after our reunion I visited a friend's summer house on the little lake Kvarnsjön in Huddinge:

Back to the Revit API, after having taken a second look at connector orientation, here is another MEP coordinate system topic that can bear updating and coincidentally also has a connection to Scandinavia, since Progman Oy and Olli are Finnish.

I recently presented the discussion with Olli Kattelus of MagiCAD at Progman Oy on defining an ECS or element coordinate system for MEP ducts and pipes.

This is required for exporting them to IFC. Their geometry is specified in ECS there so that the same element definition can be reused consistently for all of its occurrences.

That took care of ducts and pipes, but the issue of family instances was not completely resolved, especially how to handle their potentially 'flipped' geometry.

Now Olli reports an easy solution for that as well, which is actually easier and more obviously canonical than the duct and pipe one, since a family instance already has a transform that we can base our ECS on:

I managed to solve problems with those flipped objects.

I changed the style how I constructed the transform a little bit.

With fittings, I use the hand/facing orientation & location point of the family instance instead of the connector direction & location:

  Transform ^tf = Transform::Identity;

  // Create correct vectors, 
  // taking flipping into account

  XYZ ^ho = famInstance->HandFlipped 
    ? famInstance->HandOrientation->Negate() 
    : famInstance->HandOrientation;

  XYZ ^fo = famInstance->FacingFlipped 
    ? famInstance->FacingOrientation->Negate() 
    : famInstance->FacingOrientation;

  ho = ho->Normalize();
  fo = fo->Normalize();

  tf->BasisX = ho;
  tf->BasisY = fo;
  tf->BasisZ = ho->CrossProduct(fo);
  tf->Origin = famInstance->Location->Point;

  tf = tf->Inverse;

You may be wondering why we need this, since fittings are family instances whose geometry is already defined the way we need it for the IFC export.

However, a fitting may also have an insulation added to it. The InsulationLiningBase class representing the insulation is inherited from MEPCurve, so we have the same issues for defining an ECS as we did for the duct and curve.

Thus only fittings with insulation need this transform treatment, in order to export their insulation geometry, not the fitting's own one.

Many thanks to Olli for this simple and elegant solution!

Family Usage Filtered Element Collector Performance

Since all access to the Revit database and its elements takes place through the filtered element collectors, it is extremely important to make efficient use of them. We have not looked at that topic for quite a while now. Here is an issue that recently cropped up which illustrates some interesting points.

I presented a filtered element sample for creating an XML family usage report which iterates over all the loaded families and launches a new filter for each of them looking for its instances.

If you are only interested in families of certain categories, and furthermore only in ones that actually have instances in the model, then the approach presented there will almost certainly turn out to be inefficient in a large model.

That leads to the following query:

Question: I tried to get a list of families which have instance in the model (not all families), but the performance is very bad if the model has loaded hundreds of family types.

Here is the VB.NET code (copy and paste to an editor to see the truncated lines in full):

Sub GetFamilyType(ByVal mydoc As Document)
  Dim collector As New Autodesk.Revit.DB.FilteredElementCollector(mydoc)
  Dim collection As ICollection(Of Autodesk.Revit.DB.Element) = collector.OfClass(GetType(DB.Family)).ToElements()
  ' Get all families belong to a Category of current document                 
  Dim families As List(Of Family)
  Dim category As DB.Category = Nothing
  'Dim familylist As New Dictionary(Of String, Family)
  Dim familyTypeCategoryList As New Dictionary(Of String, List(Of Family)) 'Family list with Family Instance in the current model
  Dim categoryList As New Dictionary(Of String, Category) 'Category list with Family Instance in the current mode
  For Each family As DB.Family In collection
    category = Nothing
    If family.Symbols.Size > 0 Then
      Dim symbols As FamilySymbolSetIterator = family.Symbols.ForwardIterator()
      symbols.Reset()
      Dim symbol As Autodesk.Revit.DB.FamilySymbol = Nothing
      While symbols.MoveNext()
        symbol = TryCast(symbols.Current, Autodesk.Revit.DB.FamilySymbol)
        '-------------------------
        'Bad performance with following code when the model has hundreds of family types
        'Anyway to improve it?  
        '-------------------------
        'Find the symbol of which at least a Family instance exists    
        Dim filter As New DB.FamilyInstanceFilter(mydoc, symbol.Id)
        collector = New Autodesk.Revit.DB.FilteredElementCollector(mydoc)
        Dim familyInstances As ICollection(Of DB.Element) = collector.WherePasses(filter).ToElements()
        If familyInstances.Count > 0 Then
          'All symbols of a family are in the same category, different family might in then same category
          category = symbol.Category
          Exit While
        End If
      End While
      If category IsNot Nothing Then
        If familyTypeCategoryList.ContainsKey(category.Name) Then
          familyTypeCategoryList.Item(category.Name).Add(family)
        Else
          families = New List(Of DB.Family)
          families.Add(family)
          familyTypeCategoryList.Add(category.Name, families)
          categoryList.Add(category.Name, category)
        End If
      End If
    End If
  Next
End Sub

Is there a quick filter to retrieve only the families having instances in the model?

Answer: There are a few ways that this can be improved directly, and there are also some alternative approaches which may or may not improve performance, and which you would have to test yourself in your own environment using your real world models.

Remember to always benchmark your add-in performance.

One thing that I note which will cost you some unnecessary time is the conversion of collectors to collections, for instance:

  Dim collection As ICollection(
      Of Autodesk.Revit.DB.Element)
    = collector.OfClass(GetType(DB.Family))
      .ToElements()

There is no need for this conversion; you can iterate over the collector itself directly, so there is no reason to create a collection, which requires memory allocation and a conversion overhead.

Eliminating the conversion to collections will only have a small impact, though. Try it out; benchmark this and let me know the result, please.

Much more significantly, you are first collecting all the families in the model, and then launching a separate new filter for each in a loop to find all of its potential instances.

For each of the families, if any instance is found, you retrieve its category and check whether it is one of the categories of interest to you.

If not, or no instances were found, the family is skipped and all the effort spent on that family so far was wasted.

I would suggest a completely different algorithm:

1. Define the list of categories of interest to you.
2. Implement one single family instance filter for all of these categories.
3. Iterate over the result and determine which families they belong to, or which symbols they use.
4. If you use these families or symbols (or their names) as dictionary keys, you will create the desired list.
5. The dictionary value for each can be something minimal, like a count of all the family instances of each type, or larger, like a list of all the instance element ids.

The first two steps are illustrated in several places on the blog, for instance in the examples to retrieve MEP elements, connectors, and structural elements.

I'm sure the remaining steps are demonstrated somewhere as well.

You can also look at the numerous other filtered element collector samples.

The XML family usage report shows how to iterate specifically over families, which may however not help much in your case, since it looks at all families, regardless of their categories and whether they have any instances in the model.

It is thus similar to your original approach.

Actually, looking at your code, I think it may be based on that very post :-)

I hope this solves the problem for you... I think it will, actually.

Response: Thank you for your suggestion. Step 1 does not apply to our case since we don't know the categories until after we filter the family instances in the model.

Here is the code that we ended up with:

Public Shared Sub CreateFamilyTreeTest( _
  ByVal myDoc As Document)

  Dim collector As New FilteredElementCollector(myDoc)
  collector.WhereElementIsNotElementType()

  Dim familyInstances = From elem In collector _
    Where elem.Category IsNot Nothing _
    And TypeOf elem Is FamilyInstance()

  Dim familySymbols = From elem In collector _
    Join sb In familyInstances _
    On elem.UniqueId Equals CType(sb.ObjectType,
      FamilySymbol).Family.UniqueId _
    Where TypeOf elem Is Family Select elem

  familySymbols = familySymbols.Distinct()

  Dim mapCatToFam As _
    New Dictionary(Of String, List(Of Family))

  Dim categoryList As _
    New Dictionary(Of String, Category)

  Dim families As List(Of Family)
  Dim category As Category
  Dim symbol As FamilySymbol

  For Each family As Family In familySymbols
    If family.Symbols.Size > 0 Then
      symbol = family.Symbols(0)
      category = symbol.Category
      If mapCatToFam.ContainsKey(category.Name) Then
        mapCatToFam.Item(category.Name).Add(family)
      Else
        families = New List(Of Family)
        families.Add(family)
        mapCatToFam.Add(category.Name, families)
        categoryList.Add(category.Name, category)
      End If
    End If
  Next
End Sub

It uses LINQ to improve the performance and takes about 10 seconds compared to the original 3-5 minutes.

Addendum: Guy Robinson suggested below making use of the .NET generic GroupBy method to simplify this further as follows:

public static void CreateFamilyTreeTest(
  Document myDoc )
{
  IEnumerable<Element> familiesCollector =
    new FilteredElementCollector( myDoc )
      .OfClass( typeof( FamilyInstance ) )
      .WhereElementIsNotElementType()
      .Cast<FamilyInstance>()
      // (family, familyInstances):
      .GroupBy( fi => fi.Symbol.Family )
      .Select( f => f.Key );
 
  var mapCatToFam = new Dictionary<string,
    List<Element>>();
 
  var categoryList = new Dictionary<string,
    Category>();
 
  foreach( var f in familiesCollector )
  {
    var catName = f.Category.Name;
 
    if( mapCatToFam.ContainsKey( catName ) )
    {
      mapCatToFam[catName].Add( f );
    }
    else
    {
      mapCatToFam.Add( catName,
        new List<Element> { f } );
 
      categoryList.Add( catName,
        f.Category );
    }
  }
}

If you are interested in some background on the GroupBy method and an encouragement to use it whenever possible, here is a short introduction and tutorial.

Class Property Initialiser

As one thing leads to another, I wondered about the missing pair of parenthesis in the new List initialiser above, and asked Guy about that.

Guy responds: When using collection initialisers the parentheses () are optional. The code will compile and run both with and without them.

So 'new List<Element> { f, f };' is the same as writing:

  var list = new List<Element>();
  list.Add( f );
  list.Add( f );

You can also use initialisers for class properties. So say I have a class like this:

  public class Klass
  {
    public int Prop1 { get; set; }
    public string Prop2 { get; set; }
  }

A new instance of that class can be initialised like this:

  var klass = new Klass
  {
    Prop1 = 23,
    Prop2 = "some string"
  };

Saves a bit of typing ;-)

Many thanks to Guy for all his interesting hints and explanations!

Edit Family Requires No Transaction

I recently received a note from Matt Mason pointing out that the behaviour of the EditFamily method changed in Revit 2013, and a suggestion to highlight this fact. The suggestion is very valid, since his note was quickly followed up by a matching question by Woong Ki Sung on reloading a family, who ran into the very same issue:

Question: I am testing some code to edit family types in Revit 2013, and I have a transaction problem even though I set up manual transactions properly.

The code is very simple, so could you please check? In advance, thank for your help.

Here is the answer by Matt:

Answer: A quick note after I saw your recent post on upgrading add-ins.

I had an interesting case the other day: there is a new API requirement in 2013 that all transactions must be closed before calling EditFamily – it throws an exception to that effect.

I hadn't really focused on this before, and the add-in in question was actually still set up for Automatic mode – I had to convert my add-in to manual transaction mode so that I could control the transactions and close them all prior to calling EditFamily.

The remarks on the EditFamily method in the Revit 2013 API help file RevitAPI.chm now clearly state:

Gets the document of a loaded family to edit. This creates an independent copy of the family for editing. To apply the changes back to the family stored in the document, use the LoadFamily overload accepting IFamilyLoadOptions.

This method may not be called if the document is currently modifiable (has an open transaction) or is in a read-only state. The method may not be called during dynamic updates. To test the document's current status, check the values of IsModifiable and IsReadOnly properties.

Many thanks to Matt for pointing this out!