The Building Coder

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.

Filter for Family Instances in a Room

I wish you a Good Friday.

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

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

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

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

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

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

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

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

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

All of these are quick filters.

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

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

The method currently looks like this:

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

Family Instance Room Property Considerations

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

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

Considerations Processing a Complete Model

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

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

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

Revit 2014 and Supporting Columns

Revit 2014 Announced

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

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

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

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

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

Determining the Columns Supporting a Beam

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

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

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

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

Columns Supporting a Selected Beam

Here is a view of a simple sample model:

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

Simple, ain't it?

Solid and Element Intersection

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

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

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

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

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

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

The same problem also prevents use the element intersection filter.

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

Bounding Box Filter Tolerance

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

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

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

Moving the Beam Downwards in a Temporary Transaction

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

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

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

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

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

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

Time for another idea.

GetGeneratingElementIds

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

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

Cylinder Along Location Line Offset Downwards

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

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

Yay! This works!

Find References via Ray Casting

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

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

Sweep Along Location Curve Offset Downwards

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

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

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

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

All is well.

Conclusion and Source Code

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

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

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

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

Rename View by Matching Elevation Tag with Room

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4. Retrieve the room:

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

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

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

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

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

Au Bout du Monde and Super-Sonic Stereo

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

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

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

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

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

Off we go to the airport...

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.

Retrieving Schedules on a Sheet

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

Victor Chekalin picked up and expanded on that.

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

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

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

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

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

It can be used like this:

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

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

Here is the demo result:

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

The extension method is similar:

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

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

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

Here is the result of my demo project:

I attached the demo Visual Studio solution and Revit project.

I hope this information will useful for developers.

Have a nice day,
Victor.

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

ToElementIds Performance

Conversion of a filtered element collector to an explicit .NET collection of elements or element ids is always costly and mostly avoidable and unnecessary.

Before getting to the details of that issue, here is another quick snapshot from our travels to the West European developer conferences. As you either know or might guess, one of the main topics of these is cloud and mobile development, e.g. looking at topics such as the BIM 360 Glue REST API and SDK and my hands-on exploration of how to access and use it via Python.

Funnily enough, the lighting in the Paris Charles de Gaulle airport is designed along a cloud scheme, so here is very low quality picture of us almost touching the clouds at the airport gate preparing to board the flight to Milano:

Ora siamo arrivati in Milano per un'altra conferenza di sviluppatori.

Returning to the Revit API, I recently mentioned a couple of FindElement and collector optimisations.

One of them is the fact that the conversion from a filtered element collector to a .NET collection is costly and should be avoided if possible.

Here is another observation related to that, brought up by Guy Robinson and answered by Scott Conover of the Revit API development team:

Question: I sometimes use the ToElementIds method, e.g. like this:

  var fc = new FilteredElementCollector( doc )
    .OfSomething()
    .ToElementIds();
 
  foreach( var elemId in fc )
  {
    var element = doc.GetElement( elemId );
  }

I noticed that this is about 25% slower than accessing the elements directly as follows:

  var fc = new FilteredElementCollector( doc )
    .OfSomething();
 
  foreach (var elem in fc)
  {
      var element = elem;
  }

I am wondering why the ToElementIds approach is so much slower?

Shouldn't the two approaches be equivalent?

Is there any good reason to use ToElementIds at all?

Not surprisingly, this ~25% slower figure has been the same on my tests ever since I started comparing in Revit 2012.

Answer: This is not unexpected.

ToElementIds and ToElements allocate a new concrete .NET collection containing the elements passing the filter. Then it returns this allocated collection to you, which involves a conversion from a native level collection to a managed object. This will take extra time as compared to a direct iteration.

Why might you use the ToElementIds variants? Well, you might need a concrete collection to store in memory. Or you might need a collection to pass as input to an API method like Delete – which you should definitely not call from the middle of a foreach iteration unless you like unexpected behaviour. This provides a shortcut to building this allocation.

For any sort of operation of the type "I want to read properties of each passing element" you can skip ToElements and the extra collection allocation.

Thank you Scott for these insights!

For one example of how this can be achieved, look at the aforementioned FindElement and collector optimisations. There are lots of other examples in many of The Building Coder discussions, since I consciously and consistently avoid this conversion whenever possible, i.e. almost always.

Accessing all Elements in a Schedule

Here is a quick little post, with a surprisingly short and simple answer to a short and seemingly difficult Revit API question.

Before getting to that, I will just mention that I arrived safe and sound in Paris for a developer conference here. I had a walk in the sunset on the north bank of the Seine from the Gare de Lyon along the industrial areas on Quai de Bercy and crossed the river over the new-built Pont National to reach the rue de Tolbiac by a rather roundabout route.

So, back to Revit; how can we easily retrieve all the elements listed in a schedule view?

Question: The Revit 2013 API finally enabled the creation of schedule views, which is great.

I would also need to query that schedule and retrieve all the element ids of the elements contained in it.

Currently, I am using the workaround of exporting the schedule and then comparing with elements within the project, which takes a considerable amount of time.

Is there any simpler way to achieve this?

Answer: Yes, there is.

The schedule is a view, and its view id can be passed in to the filtered element collector just like any other.

That will return the relevant elements.

Sorry you had to go to all that unnecessary trouble :-)

Many thanks to Guy Robinson for pointing this out!

Ensure WPF Add-in Remains in Foreground

Autumn arrived and passed in a flash. The woods are beautifully coloured, and, unusually, the first snow is already lying on the surrounding hills.

Here are some items of interest from cases we looked at last week:

1. Ensure WPF add-in remains in foreground
2. Retrieve all model lines
3. Set linked file visibility
4. Access linked file elements and data
5. Visual Studio 2012 Model Editor Supports OBJ and FBX
6. Sie Mögen Sich

Ensure WPF Add-in Remains in Foreground

Here is an issue concerning an interaction between a WPF add-in and the Revit TaskDialog, raised and solved by Simon Hooper of Bestech Systems Ltd:

Question: I have a modal WPF Revit add-in application.

If I show a TaskDialog, e.g. call TaskDialog.Show("Global", "Hello World"), my WPF add-in is sent to 'the back' behind Revit, in spite of being modal!

If I use MessageBox.Show(""), the problem does not occur.

How can this be resolved, please?

Answer: I ensured that the WPF form properly parented, i.e. is it a child form of the Revit main application window.

Googling for "JtWindowHandle wrapper class" provides lots of examples of how to parent a normal .NET modeless form.

The procedure is applicable to WPF forms as well.

It seems like the problem is solved by using the following lines:

  exportForm = new ExportForm();
 
  System.Windows.Interop.IWin32Window revit_window 
    = new JtWindowHandle( Autodesk.Windows
      .ComponentManager.ApplicationWindow );
 
  System.Windows.Interop.WindowInteropHelper helper 
    = new System.Windows.Interop.WindowInteropHelper(
      exportForm );
 
  helper.Owner = revit_window.Handle;

The helper line was the key.

Retrieve all Model Lines

Question: I have a very simple question.

I want to scan my Revit model for all Model Line instances.

RevitLookup tells me I should use the built-in category OST_Lines in my filter, but it does not find the lines.

Here is my logic:

  FilteredElementCollector collector
    = new FilteredElementCollector( doc );
 
  ElementClassFilter familyInstanceFilter
    = new ElementClassFilter(
      typeof( FamilyInstance ) );
 
  ElementCategoryFilter oCategoryFilter
    = new ElementCategoryFilter(
      BuiltInCategory.OST_Lines );
 
  LogicalAndFilter andFilter
    = new LogicalAndFilter(
      familyInstanceFilter,
      oCategoryFilter );
 
  ICollection<Element> oElements
    = collector.WherePasses( andFilter )
      .ToElements();

However, this returns nothing at all!

What is wrong?

Answer: Yes, this is indeed a rather simple question.

Model lines are model curves. Model curves are not family instances.

Your collector includes a family instance filter. The family instance filter will eliminate all model curves, preventing any model lines from being found.

Simply remove the family instance class filter, or replace it by a model curve class filter.

By the way, the most common quick filters are all available using shortcut methods on the collector class itself.

Using the shortcut methods saves you from having to instantiate a separate filter instance, and ensures that all the filters you apply are quick filers.

All the following three variants should work, and presumably produce identical results:

  FilteredElementCollector collector
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ModelCurve ) )
      .OfCategory( BuiltInCategory.OST_Lines );
 
  FilteredElementCollector collector
    = new FilteredElementCollector( doc )
      .OfCategory( BuiltInCategory.OST_Lines );
 
  FilteredElementCollector collector
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ModelCurve ) );

Set Linked File Visibility

Saikat Bhattacharya demonstrates the use of the View class HideElements and UnhideElements methods to control the visibility of linked files, and points out that the SetVisibility method cannot be used for this purpose.

Access Linked File Elements and Data

On a still more exciting and ever recurring linked file topic, Saikat shows how easy it is to access the elements and data contained in a linked file, e.g. to read the level information of all walls in a linked file.

Visual Studio 2012 Model Editor Supports OBJ and FBX

Visual Studio 2012 includes a Model Editor that enables you to inspect the 3-D model formats OBJ, Autodesk FBX and COLLADA. You can also use built-in 3-D primitive generation and materials to create placeholder art for 3-D games and applications.

That sounds handy, doesn't it?

I recently had a look at the OBJ format to implement Revit model export to OBJ, and obviously Revit already provides built-in support for FBX export (LT, Vasari).

If you wanted to work in depth with FBX yourself, you would presumably use the FBX SDK, currently at version 2013.3, supporting C++ development in Visual Studio 2005, 2008, and 2010.

Sie Mögen Sich

For something completely unrelated to computers and technology, here is a seven minute video, Sie mögen sich, a quite deep philosophical relationship analysis by Shaban & Käptn Peng that my son Christopher pointed out and that I enjoyed a lot:

It is in German, however, and probably makes no sense at all unless you understand the language.

FindElement and Collector Optimisation

As I recently mentioned, Mikako Harada published a very nice article on programmatically adjusting beam cutback.

It was followed it up by a description of some commonly used helper methods to find certain named elements and family symbols in a project. One of them is FindElement, implemented as follows in that post:

  public static Element FindElement(
    Document doc,
    Type targetType,
    string targetName )
  {
    // Get the elements of the given class 
 
    FilteredElementCollector collector 
      = new FilteredElementCollector( doc );
 
    collector.WherePasses( 
      new ElementClassFilter( targetType ) );
 
    // Parse the collection for the 
    // given name using LINQ query.
 
    IEnumerable<Element> targetElems =
      from element in collector
      where element.Name.Equals( targetName )
      select element;
 
    IList<Element> elems = targetElems.ToList();
 
    if( elems.Count > 0 )
    {
      // We should have only one with the given name.
 
      return elems[0];
    }
 
    // Cannot find it.
 
    return null;
  }

It is important to be aware that this method can be optimised further in some aspects and should not be used indiscriminately.

Here are some points I would like to highlight:

1. Language dependence: should be avoided if possible.
2. Speed: could be improved by using a parameter filter instead of LINQ.
3. Conversion from a filtered element collector to .NET collections can often be avoided.

I avoid using the helper methods in this form wherever I can if performance is a factor. When is it not?

It is not always possible to avoid the language dependence. In any case, it is definitely important to be aware of the issue.

In detail:

1. Language dependence: if there is any way to identify the target element except by name, it is normally preferable to do so.
2. Speed: using a parameter filter to find a name may be complicated by the fact that different Revit element types store their names in different parameter values. The LINQ query can mostly be replaced by a parameter filter, though, which normally halves the execution time, since the marshalling of all the non-target data from internal Revit memory to external .NET and LINQ space is eliminated.
3. A filtered element collector is already iterable, so the conversion to an IEnumerable<Element> and to IList<Element> is often unnecessary. If all filtering can be achieved using filtered element collector functionality, the instantiation of additional lists and consequent duplication and copying of all contained data members can be completely avoided. This is obviously especially important for large collections.

I mentioned performance hints such as these numerous times in the past between the lines. Maybe the time is ripe now to bring them up as a topic of their own.

Mikako underlines that the main intention of the helper method above is to make it as easy as possible for the reader to copy and paste these code snippets to quickly run the test command instead of having to download, explore and install the whole ADN training material zip file, and performance is a completely secondary consideration.

If performance becomes a bottleneck, each developer needs examine it and implement her own optimised version. Accessing a wall type, for example, does not require this kind of filtering from the whole element list.

Collector Optimisation

While we are on the topic of efficient coding, here is another snippet of typical add-in code presenting a surprising number of opportunities for improvement in a very few lines.

It retrieves all family symbols in the document, uses them to find door families, and processes each one in turn:

  FilteredElementCollector collector 
    = new FilteredElementCollector( doc );
 
  FilteredElementIterator itor = collector
    .OfClass( typeof( FamilySymbol ) )
    .GetElementIterator();
 
  itor.Reset();
 
  while( itor.MoveNext() )
  {
    FamilySymbol symbol = itor.Current
      as Autodesk.Revit.DB.FamilySymbol;
 
    // Determine family category
 
    Category cat = symbol.Category;
 
    // Process family if doors category
 
    if( cat != null )
    {
      if( cat.Name == "Doors" )
      {
        Family family = symbol.Family;
 
        // Process reference to doors family
      }
    }
  }

Can you spot three possibilities for improvement, either a more succinct formulation, performance enhancement, or both? And manage not to peek?

Here are the ones I found, which is not to say that there are no others:

• The code can be significantly shortened by using foreach directly on the collector instead of explicitly setting up and using an iterator.
• You should avoid explicit string comparison when you can, both for reasons of performance and language independence, e.g. use the built-in category for doors instead of the category name, which might be localised.
• In this case, you could let the collector handle the category selection for you, making the code significantly more efficient.

Applying these suggestions produces this instead:

  FilteredElementCollector collector
  = new FilteredElementCollector( doc )
    .OfCategory( BuiltInCategory.OST_Doors )
    .OfClass( typeof( FamilySymbol ) );
 
  foreach( FamilySymbol symbol in collector )
  {
    Family family = symbol.Family;
 
    // Process reference to doors family
  }

Shorter, more readable, and more performant.

Since each family can contain more than one symbol, you should obviously keep track of the families already processed and skip those when looping over the symbols.

Exporting Parameter Data to Excel, and Re-importing

Did you observe the international talk like a pirate holiday yesterday?

I did not, I'm sorry to say. I only became aware of it this morning trying to find some reason why it was so quiet yesterday. Aaarrr!

Anyway, here is an update of an age-old sample application, originally created by Miroslav Schonauer for the very first Revit API training classes after the first introduction of the Revit API back in the Revit 2008 timeframe.

Miro put together a whole collection of useful samples, which survived time and changes extraordinarily well and made it through to become the Xtra Revit API training labs.

I received several queries lately on how to export data to Excel, with various follow-up options such as later including data from linked files as well, and enabling a re-import of modified data.

The FireRating SDK Sample

Actually, talking about re-importing the exported data, a simple example of this has been around all along as well. The FireRating SDK sample demonstrates:

• Creating and populating a new shared parameter in the model.
• Exporting all its values to Excel.
• Importing modified data back in from Excel to update the Revit model.

I mentioned this important sample a number of times, ever since the early beginnings of the blog, often to demonstrate how to add a shared parameter to various element types in the model:

• Adding a shared parameter to a DWG file.
• Defining a new parameter.
• Adding a shared parameter to an RFA file.
• Model group shared parameter.
• Parameter access and scheduling.

One very special use of this sample was in the special 100^th anniversary description of utilizing Revit API resources to get a beginner up to speed and running.

Because of its importance, this sample also made its way into the Revit API Xtra training labs in the shape of three commands corresponding to the steps listed above:

• Lab4_3_1_CreateAndBindSharedParam
• Lab4_3_2_ExportSharedParamToExcel
• Lab4_3_3_ImportSharedParamFromExcel

Of course, the importance of shared parameters for add-in was greatly diminished by the introduction of extensible storage.

Parameter Export to Excel Considerations

Anyway, back to the subject at hand.

The external command Lab4_2_ExportParametersToExcel in the ADN Xtra labs implements exporting all parameter data of all Revit elements to Excel. 'All' is relative, though...

It bases the selection of parameters on the standard Revit API Element.Parameters property. An attempt is made to export the values of the parameters returned in this collection, and others are ignored. Many elements do have other parameters associated with them as well, as demonstrated by BipChecker, the built-in parameter explorer. They could easily be added to the export as well, of course.

Furthermore, there are of course a multitude of other important data items not stored in parameters that might be interesting to export and potentially modify and re-import as well. It might be worthwhile checking whether RDBLink does anything like that... RDBLink was originally part of the Revit 2008, 2009 and 2010 SDKs, then matured into a subscription pack product.

The choice of Excel as an export target is not mine, nor would it normally be so. Due to popular demand, though, this command makes use of the Excel COM interface and .NET Interop to access that. It launches or attaches to a running instance of Excel and makes it visible, so you can see the work sheets and parameters being added one by one. It might be faster to make Excel invisible, and faster still to use some other library to generate the XLS file without direct access to Excel, and faster still choosing some completely different file format such as SLK, CSV, or, heaven forbid, TXT.

The command selects all elements in the entire model, both types (e.g. family symbols) and non-type elements. Each element is identified in the export by its element id, and a flag is added to tell whether it is a type or not.

The original implementation exported only model elements. Support for all elements was implemented by creating a union of two complementary filtered element collectors, which is easily possible and normally not recommended.

The elements are sorted by category, and elements with no valid category are ignored. The elements are sorted into a dictionary of separate containers for each category.

The category names are used to create individual work sheets in a new Excel work book.

The category names need some massaging to confirm with the Excel work sheet naming conventions; the name must:

• Not be blank.
• Not exceed 31 characters.
• Not contain any of the following characters:   :   \   /   ?   *   [   or   ].

In the original implementation, the entire parameter access was encapsulated in a try-catch exception handler. Many elements returned null, though, triggering and exception and slowing down the process enormously. Every exception handler is resource intensive and will significantly slow down execution and consume resources. An exception handler should be designed to handle unexpected, exceptional cases only; exceptions should be exceptional. Adding a preceding check for a null parameter before actually trying to access it speeded things up significantly. Maybe the exception handler can be removed completely?

As said, the elements are identified in the resulting Excel data by their element id. This is not a very safe method of identifying elements, because the element id may change, e.g. by work sharing operations. It would be safer to use the UniqueId instead.

When the new work book is set up, Excel automatically adds a couple of work sheets to it. The number of default work sheets added can be defined in the Excel application settings. I initially implemented code to remove the unneeded work sheets, but later commented it out to simply let them be. They don't really hurt.

For each category, all the elements are examined to determine what parameters they contain. A column is added to the work sheet for each parameter, and a header is set up listing the parameter name. We iterate over the elements in that category and add a row listing their element id, type flag, and parameter values for each.

Parameter Export to Excel Implementation

Let's summarise the steps:

• Collect all elements and sort them by category.
• Attach to or launch Excel and create a new work book.
• Loop through all the categories and set up a work sheet for each.
• Determine all parameters for the given category and create the work sheet header listing them.
• Iterate over each elements of the category and export its element id, type flag and parameter values.
• Report the results.

Here is the code implementing this as a read-only external command:

/// <summary>
/// Export all parameters for each model 
/// element to Excel, one sheet per category.
/// </summary>
[Transaction( TransactionMode.ReadOnly )]
public class Lab4_2_ExportParametersToExcel 
  : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication app = commandData.Application;
    Document doc = app.ActiveUIDocument.Document;
 
    // Extract and group the data from Revit in a 
    // dictionary, where the key is the category 
    // name and the value is a list of elements.
 
    Stopwatch sw = Stopwatch.StartNew();
 
    Dictionary<string, List<Element>> sortedElements 
      = new Dictionary<string, List<Element>>();
 
    // Iterate over all elements, both symbols and 
    // model elements, and them in the dictionary.
 
    ElementFilter f = new LogicalOrFilter(
      new ElementIsElementTypeFilter( false ), 
      new ElementIsElementTypeFilter( true ) );
 
    FilteredElementCollector collector
      = new FilteredElementCollector( doc )
        .WherePasses( f );
 
    string name;
 
    foreach( Element e in collector )
    {
      Category category = e.Category;
 
      if( null != category )
      {
        name = category.Name;
 
        // If this category was not yet encountered,
        // add it and create a new container for its
        // elements.
 
        if( !sortedElements.ContainsKey( name ) )
        {
          sortedElements.Add( name, 
            new List<Element>() );
        }
        sortedElements[name].Add( e );
      }
    }
 
    // Launch or access Excel via COM Interop:
 
    X.Application excel = new X.Application();
 
    if( null == excel )
    {
      LabUtils.ErrorMsg( 
        "Failed to get or start Excel." );
 
      return Result.Failed;
    }
    excel.Visible = true;
 
    X.Workbook workbook = excel.Workbooks.Add( 
      Missing.Value );
 
    X.Worksheet worksheet;
 
    // We cannot delete all work sheets, 
    // Excel requires at least one.
    //
    //while( 1 < workbook.Sheets.Count ) 
    //{
    //  worksheet = workbook.Sheets.get_Item(1) as X.Worksheet;
    //  worksheet.Delete();
    //}
 
    // Loop through all collected categories and 
    // create a worksheet for each except the first.
    // We sort the categories and work trough them 
    // from the end, since the worksheet added last 
    // shows up first in the Excel tab.
 
    List<string> keys = new List<string>( 
      sortedElements.Keys );
 
    keys.Sort();
    keys.Reverse();
 
    bool first = true;
 
    int nElements = 0;
    int nCategories = keys.Count;
 
    foreach( string categoryName in keys )
    {
      List<Element> elementSet 
        = sortedElements[categoryName];
 
      // Create and name the worksheet
 
      if( first )
      {
        worksheet = workbook.Sheets.get_Item( 1 ) 
          as X.Worksheet;
 
        first = false;
      }
      else
      {
        worksheet = excel.Worksheets.Add( 
          Missing.Value, Missing.Value, 
          Missing.Value, Missing.Value ) 
          as X.Worksheet;
      }
 
      name = ( 31 < categoryName.Length )
        ? categoryName.Substring( 0, 31 )
        : categoryName;
 
      name = name
        .Replace( ':', '_' )
        .Replace( '/', '_' );
 
      worksheet.Name = name;
 
      // Determine the names of all parameters 
      // defined for the elements in this set.
 
      List<string> paramNames = new List<string>();
 
      foreach( Element e in elementSet )
      {
        ParameterSet parameters = e.Parameters;
 
        foreach( Parameter parameter in parameters )
        {
          name = parameter.Definition.Name;
 
          if( !paramNames.Contains( name ) )
          {
            paramNames.Add( name );
          }
        }
      }
      paramNames.Sort();
 
      // Add the header row in bold.
 
      worksheet.Cells[1, 1] = "ID";
      worksheet.Cells[1, 2] = "IsType";
 
      int column = 3;
 
      foreach( string paramName in paramNames )
      {
        worksheet.Cells[1, column] = paramName;
        ++column;
      }
      var range = worksheet.get_Range( "A1", "Z1" );
 
      range.Font.Bold = true;
      range.EntireColumn.AutoFit();
 
      int row = 2;
 
      foreach( Element e in elementSet )
      {
        // First column is the element id,
        // second a flag indicating type (symbol)
        // or not, both displayed as an integer.
 
        worksheet.Cells[row, 1] = e.Id.IntegerValue;
 
        worksheet.Cells[row, 2] = (e is ElementType) 
          ? 1 
          : 0;
 
        column = 3;
 
        string paramValue;
 
        foreach( string paramName in paramNames )
        {
          paramValue = "*NA*";
 
          Parameter p = e.get_Parameter( paramName );
 
          if( null != p )
          {
            //try
            //{
              paramValue 
                = LabUtils.GetParameterValue( p );
            //}
            //catch( Exception ex )
            //{
            //  Debug.Print( ex.Message );
            //}
          }
 
          worksheet.Cells[row, column++] 
            = paramValue;
        } // column
 
        ++nElements;
        ++row;
 
      } // row
 
    } // category == worksheet
 
 
    sw.Stop();
 
    TaskDialog.Show( "Parameter Export",
      string.Format(
        "{0} categories and a total "
        + "of {1} elements exported "
        + "in {2:F2} seconds.",
        nCategories, nElements,
        sw.Elapsed.TotalSeconds ) );
 
    return Result.Succeeded;
  }
}

I ran the command on the basic architectural sample model rac_basic_sample_project.rvt. It takes about two minutes to complete, produces this XLS file output containing 124 work sheets, and displays the following message on terminating:

The timing is not very relevant, since I was doing other things at the same time on the machine.

Here is adn_labs_2013_2012-09-19.zip containing the complete source code, Visual Studio solution and RvtSamples include file of the ADN training labs with the updated Lab4_2_ExportParametersToExcel external command.

Filter for Touching Beams Using Solid Intersection

I discussed how I created my first sphere in the Revit API and displayed it using the analysis visualisation framework AVF. Now let's make more serious use of it.

As I mentioned, the transient solids created by the geometry creation utility class can be used to set up geometrical proximity filters.

This exploration was prompted by the following query:

Question: I would like to programmatically retrieve all touching beams, regardless of whether they are officially connected or not.

The user should pick one single beam, and all other beams touching it should be selected, recursively.

How can I achieve this, please?

Answer: First let's look at the case you are not interested in :-)

If the beams are properly connected, you can use the LocationCurve ElementsAtJoin property to determine the connected beams at each end of the first, manually selected one, and iterate through the connection elements as demonstrated by the TraverseSystem SDK sample for duct systems using the MEP connector manager.

If the beams are not properly connected, but just touching, as you say, you can use the ElementIntersectsSolidFilter instead. Such as filter detects elements within a given geometrical space defined by solid, which may come from the BIM model or be transient, i.e. generated in memory on the fly.

To recursively iterate through the beam system requires creating a new solid and a new filter for each beam you find, since each solid has its own location in space. If you are interested in beams touching anywhere, you could create an extruded shape matching the beam shape and detect all other beams that intersect it or come close to it anywhere at all along the length of the beam. If you are only interested in beams touching at the end points, you could set up a simple sphere at each end of the beam.

This process could be repeated recursively for all touching beams encountered. Of course you would have to skip beams that you have already found, or you would run into an infinite loop.

Here is the algorithm I am thinking of:

• Maintain three lists of beams:
  • The beams already visited.
  • The current ones being analysed.
  • The neighbours of the current ones.
• Select a starting beam, making it the current one.
• While the set of current beams is non-empty, repeat the following:
  • Add the current to the list of visited beams.
  • Clear the list of neighbours.
  • For each of the current beams, add all beams touching it to the list of neighbours.
  • Make the neighbours found in the previous step the new set of current beams.

Finding all touching neighbours for a given beam is implement in the method AddConnectedElements, which sets up a sphere at each end of the beam, creates a proximity detector based on it using an ElementIntersectsSolidFilter, and adds all beams retrieved by that, excluding the beams already visited and neighbours already found.

I already presented the sphere creation method CreateSphereAt.

Here is the AddConnectedElements method and its helper method AddElementsIntersectingSphereAt to detect touching elements:

  /// <summary>
  /// Determine all neighbouring elements connected
  /// to the current element 'e', skipping all 
  /// previously visited ones.
  /// </summary>
  void AddElementsIntersectingSphereAt(
    List<ElementId> neighbours,
    XYZ p,
    List<ElementId> visited,
    Document doc )
  {
    Solid sphere = CreateSphereAt(
      doc.Application.Create, p, _sphere_radius );
 
    ElementIntersectsSolidFilter intersectSphere
      = new ElementIntersectsSolidFilter( sphere );
 
    FilteredElementCollector collector
      = new FilteredElementCollector( doc )
        .WhereElementIsCurveDriven() // we work with the location curve
        .OfCategory( _bic )
        .Excluding( visited.Union<ElementId>( 
          neighbours ).ToList<ElementId>() )
        .WherePasses( intersectSphere );
 
    neighbours.AddRange( collector.ToElementIds() );
  }
 
  /// <summary>
  /// Determine all neighbouring elements close to 
  /// the two ends of the current element 'e', 
  /// skipping all previously visited ones.
  /// </summary>
  void AddConnectedElements(
    List<ElementId> neighbours,
    Element e,
    List<ElementId> visited )
  {
    Location loc = e.Location;
 
    Debug.Print( string.Format(
      "current element {0} has location {1}",
      ElementDescription( e ),
      null == loc ? "<null>" : loc.GetType().Name ) );
 
    LocationCurve lc = loc as LocationCurve;
 
    if( null != lc )
    {
      Document doc = e.Document;
 
      Curve c = lc.Curve;
 
      XYZ p = c.get_EndPoint( 0 );
      XYZ q = c.get_EndPoint( 1 );
 
      AddElementsIntersectingSphereAt(
        neighbours, p, visited, doc );
 
      AddElementsIntersectingSphereAt(
        neighbours, q, visited, doc );
    }
  }

The lists of neighbours and visited elements are implemented as collections of ElementId instead of Element instances, since I do not trust the .NET comparison methods to work properly on Elements. Also, this aligns nicely with the Exclude method on the filtered element collector, which takes a collection of element ids as an argument.

I initially tried calling Exclude twice with separate calls for the lists of already visited elements and neighbours, both of which should be eliminated. In the first call, though, the list of neighbours is always empty. Providing an empty list to the Exclude method throws an exception. I could have called the Exclude method conditionally, checking first that the list of neighbours is non-empty. However, I found it more succinct to combine the two lists into a single one for the call.

With the AddConnectedElements method in place, the algorithm described above translates to the following C# implementation of the external command Execute mainline method:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
  CreationApp creapp = app.Create;
  Document doc = uidoc.Document;
  Selection sel = uidoc.Selection;
  Reference r = null;
 
  try
  {
    r = sel.PickObject(
      ObjectType.Element,
      "Please select a beam" );
  }
  catch( RvtOperationCanceledException )
  {
    return Result.Cancelled;
  }
 
  // Starting element
 
  Element start = doc.GetElement( r );
 
  // The current elements whose neighbours 
  // we are seeking
 
  List<ElementId> current = new List<ElementId>();
 
  current.Add( start.Id );
 
  // List of elements already visited
 
  List<ElementId> visited = new List<ElementId>();
 
  // Continue as long as new connected 
  // elements are found
 
  List<ElementId> neighbours = new List<ElementId>();
 
  while( 0 < current.Count )
  {
    // Remember where we have been, add this to 
    // the result so far, and do not revisit these
 
    visited.AddRange( current );
 
    // We found no new neighbours yet
 
    neighbours.Clear();
 
    // Search current elements for new connected 
    // elements not already visited
 
    foreach( ElementId id in current )
    {
      Element e = doc.GetElement( id );
 
      AddConnectedElements(
        neighbours, e, visited );
    }
 
    // Done with the current elements, and the
    // newly found become the next current ones
 
    current.Clear();
    current.AddRange( neighbours );
  }
 
  foreach( ElementId id in visited )
  {
    uidoc.Selection.Elements.Add(
      doc.GetElement( id ) );
  }
  return Result.Succeeded;
}

Pretty neat, huh?

And pretty readable, I think?

Here is a sample model with several sets of touching but not officially connected beams: two sets of two beams each on the right-hand side of the room in the middle, and a bunch of more beams all touching along the left, top and bottom. Some of them are longer than others and stretch across several columns:

After running the command and picking any single one of the beams on the left, the connected elements are all selected and therefore highlighted in blue, whereas the unconnected ones on the right remain unhighlighted:

Note that this approach is useful for any curve based element, so it could also be adapted to find all touching walls, ducts, pipes, and many other object types.

Here is SelectTouchingBeams.zip containing the source code, Visual Studio solution and add-in manifest of the 'Select Touching Beams' command. It also includes the Display Sphere command that I discussed in the previous post.

Set View Section Box to Match Scope Box

Here is a case that I really like, demonstrating two interesting aspects:

• How to retrieve the exact geometric location, size and orientation of the scope box.
• How to set the exact geometric location, size and orientation of the 3D view section box.

In fact, we show how to use the manually adjusted scope box to define the view section box, i.e. specifying exactly how the model is cut in the current 3D view.

I actually already showed how to set up a view section box discussing how to create a section view parallel to a wall.

The key is setting up the view SectionBox property properly. It takes a BoundingBoxXYZ input, i.e. a transform plus minimum and maximum values describing the location, orientation and size of the box. In that post, it is fed into the CreateSection method.

To manipulate an existing view instead of creating a new one, you simply set up the bounding box in the same way and assign it to the view SectionBox property as shown below.

Here is the discussion that led up to this solution:

Question: Here is a model in 3D view containing a scope box represented by the dotted lines. The 3D view SectionBox property is checked, so the view SectionBox is also shown, using solid lines. Both are selected, and thus highlighted in blue:

Our goal is to programmatically relocate and rotate the section box so it is at the same location and angle as the scope box, and also make the size of the section box the same as the scope box.

How can this be achieved, please?

Answer: You need to implement the following workflow, or rather data flow:

1. Extract the required data from the scope box.
2. Set up the required view SectionBox bounding box data, i.e. transform, min and max points.
3. Apply the SectionBox data to the view.

The last step 3. is trivial: you simply say view.SectionBox = newSectionBox as shown below.

Step 2 is demonstrated by the discussion on how to create a section view parallel to a wall.

Step 1 requires reading and interpreting the scope box data. The scope box Location property data is not accessible, so you can't use that. As far as I can tell, the only thing you have to go by is its geometry definition.

Exploring the scope box geometry in RevitLookup, you can see that it consists of exactly twelve lines, the edges of the scope box parallelepiped itself.

You need to figure out the exact size and orientation from those twelve lines, and then decide how they should determine the view section box.

I implemented a sample command SetSectionBox to test the concept, and a method GetScopeBoxBoundingBox to extract the scope box line geometry data, create a bounding box from that, and assign it to the view section box.

It returns the minimal aligned bounding box for a Revit scope box element. The only information we can obtain from the scope box are its 12 boundary lines. Algorithm:

• Pick an arbitrary line as the X axis and its starting point as the origin.
• Find the three other lines starting or ending at the origin, and use them to define the Y and Z axes.
• If necessary, swap Y and Z to form a right-handed coordinate system.

Determining Coordinate System Right-Handedness

Ah, yes, before we get to that, how do we determine whether the three vectors form a right-handed coordinate system?

Well, the coordinate system is right handed if and only if the signed volume of the parallelepiped they span is positive. That volume is calculated by forming the cross product of the first two, then forming the dot product between the result and the third. This is also called Spatprodukt in German. Here are the two little one-line helper methods implementing this:

/// <summary>
/// Return the signed volume of the paralleliped 
/// spanned by the vectors a, b and c. In German, 
/// this is also known as Spatprodukt.
/// </summary>
static double SignedParallelipedVolume(
  XYZ a,
  XYZ b,
  XYZ c )
{
  return a.CrossProduct( b ).DotProduct( c );
}
 
/// <summary>
/// Return true if the three vectors a, b and c 
/// form a right handed coordinate system, i.e.
/// the signed volume of the paralleliped spanned 
/// by them is positive.
/// </summary>
bool IsRightHanded( XYZ a, XYZ b, XYZ c )
{
  return 0 < SignedParallelipedVolume( a, b, c );
}
 

Determining Bounding Box of Scope Box

With that out of the way, here is the code of GetScopeBoxBoundingBox implementing the functionality described above:

BoundingBoxXYZ GetScopeBoxBoundingBox(
  Element scopeBox )
{
  Document doc = scopeBox.Document;
  Application app = doc.Application;
  Options opt = app.Create.NewGeometryOptions();
  GeometryElement geo = scopeBox.get_Geometry( opt );
  int n = geo.Count<GeometryObject>();
 
  if( 12 != n )
  {
    throw new ArgumentException( "Expected exactly"
      + " 12 lines in scope box geometry" );
  }
 
  XYZ origin = null;
  XYZ vx = null;
  XYZ vy = null;
  XYZ vz = null;
 
  // Extract the X, Y and Z axes from the lines
 
  foreach( GeometryObject obj in geo )
  {
    Debug.Assert( obj is Line,
      "expected only lines in scope box geometry" );
 
    Line line = obj as Line;
 
    XYZ p = line.get_EndPoint( 0 );
    XYZ q = line.get_EndPoint( 1 );
    XYZ v = q - p;
 
    if( null == origin )
    {
      origin = p;
      vx = v;
    }
    else if( p.IsAlmostEqualTo( origin )
      || q.IsAlmostEqualTo( origin ) )
    {
      if( q.IsAlmostEqualTo( origin ) )
      {
        v = v.Negate();
      }
      if( null == vy )
      {
        Debug.Assert( IsPerpendicular( vx, v ),
          "expected orthogonal lines in scope box geometry" );
 
        vy = v;
      }
      else
      {
        Debug.Assert( null == vz,
          "expected exactly three orthogonal lines to originate in one point" );
 
        Debug.Assert( IsPerpendicular( vx, v ),
          "expected orthogonal lines in scope box geometry" );
 
        Debug.Assert( IsPerpendicular( vy, v ),
          "expected orthogonal lines in scope box geometry" );
 
        vz = v;
 
        if( !IsRightHanded( vx, vy, vz ) )
        {
          XYZ tmp = vz;
          vz = vy;
          vy = tmp;
        }
        break;
      }
    }
  }
 
  // Set up the transform
 
  Transform t = Transform.Identity;
  t.Origin = origin;
  t.BasisX = vx.Normalize();
  t.BasisY = vy.Normalize();
  t.BasisZ = vz.Normalize();
 
  Debug.Assert( t.IsConformal,
    "expected resulting transform to be conformal" );
 
  // Set up the bounding box
 
  BoundingBoxXYZ bb = new BoundingBoxXYZ();
  bb.Transform = t;
  bb.Min = XYZ.Zero;
  bb.Max = vx + vy + vz;
 
  return bb;
}

The result is close, but no cigar yet:

Determining Suitable View Section Box from Scope Box

In a next step, I decided to ensure that the Z axis I define actually is vertical and pointing upwards, take the view direction into account as well, and use the scope box edge closest to the viewer as the section box Z axis.

I therefore implemented a new method GetSectionBoundingBoxFromScopeBox, which returns a suitable bounding box for a Revit section view from the scope box position, taking the view direction into account, by performing the following steps:

1. Find vertical edge closest to viewer.
2. Use its bottom endpoint as the origin.
3. Find the other two edges emanating from the origin.
4. Use the three edges for the bounding box definition.

To find the vertical edge closest to the viewer, the view direction and scope box bounding box giving its maximum size are used together to determine a view point from which we imagine we are looking at the scope box.

I loop through the twelve lines in the scope box geometry twice. In the first loop, I determine the origin and Z axis. In the second, the X and Y axes are determined as well, based on that information.

The implementation looks like this:

BoundingBoxXYZ GetSectionBoundingBoxFromScopeBox(
  Element scopeBox,
  XYZ viewdirTowardViewer )
{
  Document doc = scopeBox.Document;
  Application app = doc.Application;
 
  // Determine a possible view point outside the 
  // scope box extents in the direction of the 
  // viewer.
 
  BoundingBoxXYZ bb 
    = scopeBox.get_BoundingBox( null );
 
  XYZ v = bb.Max - bb.Min;
 
  double size = v.GetLength();
 
  XYZ viewPoint = bb.Min 
    + 10 * size * viewdirTowardViewer;
 
  // Retrieve scope box geometry, 
  // consisting of exactly twelve lines.
 
  Options opt = app.Create.NewGeometryOptions();
  GeometryElement geo = scopeBox.get_Geometry( opt );
  int n = geo.Count<GeometryObject>();
 
  if( 12 != n )
  {
    throw new ArgumentException( "Expected exactly"
      + " 12 lines in scope box geometry" );
  }
 
  // Determine origin as the bottom endpoint of 
  // the edge closest to the viewer, and vz as the 
  // vertical upwards pointing vector emanating
  // from it. (Todo: if several edges are equally 
  // close, pick the leftmost one, assuming the 
  // given view direction and Z is upwards.)
 
  double dist = double.MaxValue;
  XYZ origin = null;
  XYZ vx = null;
  XYZ vy = null;
  XYZ vz = null;
  XYZ p, q;
 
  foreach( GeometryObject obj in geo )
  {
    Debug.Assert( obj is Line,
      "expected only lines in scope box geometry" );
 
    Line line = obj as Line;
 
    p = line.get_EndPoint( 0 );
    q = line.get_EndPoint( 1 );
    v = q - p;
 
    if( IsVertical( v ) )
    {
      if( q.Z < p.Z )
      {
        p = q;
        v = v.Negate();
      }
 
      if( p.DistanceTo( viewPoint ) < dist )
      {
        origin = p;
        dist = origin.DistanceTo( viewPoint );
        vz = v;
      }
    }
  }
 
  // Find the other two axes emanating from the 
  // origin, vx and vy, and ensure right-handedness
 
  foreach( GeometryObject obj in geo )
  {
    Line line = obj as Line;
 
    p = line.get_EndPoint( 0 );
    q = line.get_EndPoint( 1 );
    v = q - p;
 
    if( IsVertical( v ) ) // already handled this
    {
      continue;
    }
 
    if( p.IsAlmostEqualTo( origin )
      || q.IsAlmostEqualTo( origin ) )
    {
      if( q.IsAlmostEqualTo( origin ) )
      {
        v = v.Negate();
      }
      if( null == vx )
      {
        Debug.Assert( IsPerpendicular( vz, v ),
          "expected orthogonal lines in scope box geometry" );
 
        vx = v;
      }
      else
      {
        Debug.Assert( null == vy,
          "expected exactly three orthogonal lines to originate in one point" );
 
        Debug.Assert( IsPerpendicular( vz, v ),
          "expected orthogonal lines in scope box geometry" );
 
        Debug.Assert( IsPerpendicular( vx, v ),
          "expected orthogonal lines in scope box geometry" );
 
        vy = v;
 
        if( !IsRightHanded( vx, vy, vz ) )
        {
          XYZ tmp = vx;
          vx = vy;
          vy = tmp;
        }
        break;
      }
    }
  }
 
  // Set up the transform
 
  Transform t = Transform.Identity;
  t.Origin = origin;
  t.BasisX = vx.Normalize();
  t.BasisY = vy.Normalize();
  t.BasisZ = vz.Normalize();
 
  Debug.Assert( t.IsConformal,
    "expected resulting transform to be conformal" );
 
  // Set up the bounding box
 
  bb = new BoundingBoxXYZ();
  bb.Transform = t;
  bb.Min = XYZ.Zero;
  bb.Max = vx + vy + vz;
 
  return bb;
}

Putting it Together

Finally, let's take a look at the Execute method tying together and making use of this functionality.

For quick testing purposes, it assumes that a 3D view is currently active, and picks the first (only) scope box element it encounters. It performs the following steps:

• Access the current view and test that it is a 3D one.
• Select the scope box element.
• Determine the new view section box from the scope box using the GetSectionBoundingBoxFromScopeBox method, taking the view direction into account.
• Assign the new view section box definition to the view SectionBox property.

Here is the code:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
  Document doc = uidoc.Document;
 
  View3D view = doc.ActiveView as View3D;
 
  if( null == view )
  {
    message = "Please run this command in a 3D view.";
    return Result.Failed;
  }
 
  Element scopeBox
    = new FilteredElementCollector( doc, view.Id )
      .OfCategory( BuiltInCategory.OST_VolumeOfInterest )
      .WhereElementIsNotElementType()
      .FirstElement();
 
  BoundingBoxXYZ viewSectionBox 
    = GetSectionBoundingBoxFromScopeBox(
      scopeBox, view.ViewDirection );
 
  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "Move And Resize Section Box" );
 
    view.SectionBox = viewSectionBox;
 
    tx.Commit();
  }
  return Result.Succeeded;

The result in the original model looks like this, which is exactly what we were after:

The dotted lines representing the scope box are completely obscured by the continuous view section box lines after running the command.

Nice, huh?

Here is SetSectionBox.zip containing the complete source code, Visual Studio solution, and add-in manifest of this command.

Room in Area Predicate via Point in Polygon Test

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

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

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

Jeroen explains:

I can now implement the point in polygon test.

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

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

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

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

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

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

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

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

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

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

Many thanks to Jeroen for this discussion and nice example!

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

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

Enjoy!

OBJ Model Exporter Take One

Before continuing on the OBJ model exporter, I would like to mention I was finally up in the alps again for the first time in ages last weekend, to climb the Vrenelisgärtli mountain in Glarus, "Verena's Little Garden".

If you would like to skip straight to the meaty stuff, though, here is a table of contents:

• AEC DevCamp 2012 material finalised
• Disk full
• Model up to cloud and down to mobile
• Face emitter interface
• OBJ exporter implementation
• Retrieving a solid from an element
• Exporting an element
• Exporting all collected elements
• Exporter mainline
• Export results

The mountain name is shrouded in legend and presumably originated in the cooling down of the Little Ice Age. In the summer of 2003, the firn fields, which can be seen from far away, became snow-free for the first time again since then. Right now they are covered again :-)

The weather was fantastic on the summit, although it looked as if all the rest of the country including all other mountains were covered in clouds. Here is a view of the descent afterwards back down over the Glärnischfirn glacier (more photos):

AEC DevCamp 2012 Material Finalised

As Mikako Harada just pointed out, the final version of the AEC DevCamp 2012 material is now available and has been relocated to its two final archival sites:

• For ADN members: ADN extranet > Events > Autodesk DevCamps 2012
• Public: ADN Archive > AEC DevCamp - June 6, 2012

For more information on the content, please refer to

• The overview of the five tracks and the classes in each
• Day one of the Revit advanced track
• Most of day two of the Revit advanced track
• The complete list of classes and course descriptions

I hope you will find this material useful.

Please note that the temporary DevCamp 2012 project site on Buzzsaw which was used during the event and up until now will be closed on July 2^nd.

Once again, many thanks to all participants! It was great to have you there and meet!

Disk Full

Unfortunately, I spent much less time than expected on fun stuff, since almost all my time yesterday and this morning went to shuffling around gigabytes of files on my overfilled PC and external hard disk.

I was still using the Revit Quasar release preview, which suddenly stopped working. No big surprise, of course.

To obtain a one-box version, I went for the ultimate design suite, which requires downloading seven 4 GB files for a grand total of 27.3 GB. After finally creating enough space for them and freeing up as much as possible for installation, I launched the installer. It took an hour or longer to just copy temporary files and then aborted with a disk full error before even starting the installation proper.

I just went out and bought a new and bigger external hard disk, and am still working at freeing up more space. Very time consuming business, this.

I later found two other helpful items which gave me another couple of gig:

• Delete the Windows installer cache:
  1. Open Disk Cleanup: Start > Run > cleanmgr > OK. This will launch the Disk Cleanup utility.
  2. Select 'Temporary Files', the Windows Installer cache directory.
  3. Click OK.
• Clear the CCM cache:
  1. Select Start > Settings > Control Panel.
  2. Double click 'Configuration Manager' and open the 'Advanced' tab.
  3. Change the location of future cached files, if needed, by clicking the 'Change Location' button and choosing a new location on your hard drive. The default location is '%windir%\system32\CCM\Cache.'
  4. Delete all cached files in CCM by clicking the 'Delete Files' button. Press 'Yes' if asked to confirm.
  5. Click 'OK' to save changes and exit the Advanced window.

I'm up to 44 GB free space now...

Meanwhile, I can talk about what I did for the OBJ exporter before uninstalling Quasar RP.

Model up to Cloud and Down to Mobile

As I explained yesterday in the basic Revit model export considerations, the purpose of this exercise is to push Revit model data up to the cloud and provide access to it from mobile devices.

Adam Nagy is also currently discussing a similar project on the AEC DevBlog. After presenting his Revit add-in to upload geometry data to a storage service, the second instalment discusses an iOS application to download and display the data using OpenGL.

One thing that I am thinking of doing is to define a flexible exporter architecture so that different export targets can easily be plugged in, for instance to switch between different file formats and disk-based versus cloud-based repositories.

Face Emitter Interface

For the moment, I am working with the following pretty trivial interface definition which only specifies one single output method to export a Revit geometry face:

interface IJtFaceEmitter
{
  /// <summary>
  /// Emit a face with a specified colour.
  /// </summary>
  int EmitFace( Face face, Color color );
 
  /// <summary>
  /// Return the final triangle count 
  /// after processing all faces.
  /// </summary>
  int GetFaceCount();
 
  /// <summary>
  /// Return the final triangle count 
  /// after processing all faces.
  /// </summary>
  int GetTriangleCount();
 
  /// <summary>
  /// Return the final vertex count 
  /// after processing all faces.
  /// </summary>
  int GetVertexCount();
}

It also provides methods to query the number of exported faces and the resulting triangles and vertices when finished. I would have liked to define the count methods as simple properties instead, but that apparently cannot be done in an interface specification, unfortunately.

OBJ Exporter Implementation

The OBJ exporter class implementing this interface makes use of the vertex lookup dictionaries that I discussed yesterday to eliminate duplicate vertices. Initially I used the XYZ-based lookup class, and later I switched to the integer-based one instead.

The exported implements the four methods required by the interface definition plus a fifth method to save the resulting file:

• EmitFace: export a Revit geometry Face object.
• GetFaceCount, GetTriangleCount, GetVertexCount: return object counts.
• ExportTo: save the resulting OBJ file.

The helper method StoreTriangle is called by EmitFace to populate the vertex lookup dictionary and triangle list.

The helper methods EmitVertex and EmitFacet are called by ExportTo to write out the OBJ vertex and face records.

class ObjExporter : IJtFaceEmitter
{
  //VertexLookupXyz _vertices;
  VertexLookupInt _vertices;
 
  /// <summary>
  /// List of triangles, defined as 
  /// triples of vertex indices.
  /// </summary>
  List<int> _triangles;
 
  /// <summary>
  /// Keep track of the number of faces processed.
  /// </summary>
  int _faceCount;
 
  /// <summary>
  /// Keep track of the number of triangles processed.
  /// </summary>
  int _triangleCount;
 
  public ObjExporter()
  {
    _faceCount = 0;
    _triangleCount = 0;
    _vertices = new VertexLookupInt();
    _triangles = new List<int>();
  }
 
  /// <summary>
  /// Add the vertices of the given triangle to our
  /// vertex lookup dictionary and emit a triangle.
  /// </summary>
  void StoreTriangle( MeshTriangle triangle )
  {
    for( int i = 0; i < 3; ++i )
    {
      XYZ p = triangle.get_Vertex( i );
      PointInt q = new PointInt( p );
      _triangles.Add( _vertices.AddVertex( q ) );
    }
  }
 
  /// <summary>
  /// Emit a Revit geometry Face object and 
  /// return the number of resulting triangles.
  /// </summary>
  public int EmitFace( Face face, Color color )
  {
    ++_faceCount;
 
    Mesh mesh = face.Triangulate();
 
    int n = mesh.NumTriangles;
 
    Debug.Print( " {0} mesh triangles", n );
 
    for( int i = 0; i < n; ++i )
    {
      ++_triangleCount;
 
      MeshTriangle t = mesh.get_Triangle( i );
 
      StoreTriangle( t );
    }
    return n;
  }
 
  public int GetFaceCount()
  {
    return _faceCount;
  }
 
  /// <summary>
  /// Return the number of triangles processed.
  /// </summary>
  public int GetTriangleCount()
  {
    int n = _triangles.Count;
 
    Debug.Assert( 0 == n % 3,
      "expected a multiple of 3" );
 
    Debug.Assert( _triangleCount.Equals( n / 3 ),
      "expected equal triangle count" );

    return _triangleCount;
  }
 
  public int GetVertexCount()
  {
    return _vertices.Count;
  }
 
  #region ExportTo: output the OBJ file
  /// <summary>
  /// Obsolete: emit an XYZ vertex.
  /// </summary>
  static void EmitVertex( StreamWriter s, XYZ p )
  {
    s.WriteLine( "v {0} {1} {2}",
      Util.RealString( p.X ),
      Util.RealString( p.Y ),
      Util.RealString( p.Z ) );
  }
 
  /// <summary>
  /// Emit a vertex to OBJ. The first vertex listed 
  /// in the file has index 1, and subsequent ones
  /// are numbered sequentially.
  /// </summary>
  static void EmitVertex(
    StreamWriter s,
    PointInt p )
  {
    s.WriteLine( "v {0} {1} {2}", p.X, p.Y, p.Z );
  }
 
  /// <summary>
  /// Emit an OBJ triangular face.
  /// </summary>
  static void EmitFacet(
    StreamWriter s,
    int i,
    int j,
    int k )
  {
    s.WriteLine( "f {0} {1} {2}",
      i + 1, j + 1, k + 1 );
  }
 
  public void ExportTo( string path )
  {
    using( StreamWriter s = new StreamWriter( path ) )
    {
      foreach( PointInt key in _vertices.Keys )
      {
        EmitVertex( s, key );
      }
 
      int i = 0;
      int n = _triangles.Count;
 
      while( i < n )
      {
        int i1 = _triangles[i++];
        int i2 = _triangles[i++];
        int i3 = _triangles[i++];
 
        EmitFacet( s, i1, i2, i3 );
      }
    }
  }
  #endregion // ExportTo: output the OBJ file
}

The command mainline makes use of three other helper methods:

• GetSolid: Retrieve the first non-empty solid found for a given element.
• ExportElement: Export an individual element.
• ExportElements: Export all elements retrieved by a filtered element collector.

Retrieving a Solid from an Element

The GetSolid helper method retrieves the first non-empty solid found for a given element.

In case it is a family instance, it may have its own non-empty solid, in which case we use that. Otherwise we search the symbol geometry. If we use the symbol geometry, we might have to keep track of the instance transform to map it to the actual instance project location. Instead, we ask for transformed geometry to be returned, so the resulting solid is already in place:

Solid GetSolid( Element e, Options opt )
{
  Solid solid = null;
 
  GeometryElement geo = e.get_Geometry( opt );
 
  if( null != geo )
  {
    if( e is FamilyInstance )
    {
      geo = geo.GetTransformed(
        Transform.Identity );
    }
 
    GeometryInstance inst = null;
    //Transform t = Transform.Identity;
 
    foreach( GeometryObject obj in geo )
    {
      solid = obj as Solid;
 
      if( null != solid
        && 0 < solid.Faces.Size )
      {
        break;
      }
 
      inst = obj as GeometryInstance;
    }
 
    if( null == solid && null != inst )
    {
      geo = inst.GetSymbolGeometry();
      //t = inst.Transform;
 
      foreach( GeometryObject obj in geo )
      {
        solid = obj as Solid;
 
        if( null != solid
          && 0 < solid.Faces.Size )
        {
          break;
        }
      }
    }
  }
  return solid;
}

Exporting an Element

The ExportElement helper method exports a given element and returns the number of solids found and exported from it.

If the element is a group, this method is called recursively on the group members, so the return value may be greater than one:

int ExportElement(
  IJtFaceEmitter emitter,
  Element e,
  Options opt )
{
  Group group = e as Group;
 
  if( null != group )
  {
    int n = 0;
 
    foreach( ElementId id 
      in group.GetMemberIds() )
    {
      Element e2 = e.Document.GetElement(
        id );
 
      n += ExportElement( emitter, e2, opt );
    }
    return n;
  }
 
  string desc = Util.ElementDescription( e );
 
  if( null == e.Category )
  {
    Debug.Print( "Element '{0}' has no "
      + "category.", desc );
 
    return 0;
  }
 
  Solid solid = GetSolid( e, opt );
 
  if( null == solid )
  {
    Debug.Print( "Unable to access "
      + "solid for element {0}.", desc );
 
    return 0;
  }
 
  Material material;
  Color color;
 
  foreach( Face face in solid.Faces )
  {
    material = e.Document.GetElement(
      face.MaterialElementId ) as Material;
 
    color = ( null == material )
      ? null
      : material.Color;
 
    emitter.EmitFace( face, color );
  }
  return 1;
}

Exporting all Collected Elements

The ExportElements helper method exports all elements returned by a filtered element collector and reports the results:

void ExportElements(
  IJtFaceEmitter emitter,
  FilteredElementCollector collector,
  Options opt )
{
  int nElements = 0;
  int nSolids = 0;
 
  foreach( Element e in collector )
  {
    ++nElements;
 
    nSolids += ExportElement( emitter, e, opt );
  }
 
  int nFaces = emitter.GetFaceCount();
  int nTriangles = emitter.GetTriangleCount();
  int nVertices = emitter.GetVertexCount();
 
  string msg = string.Format(
    "{0} element{1} with {2} solid{3}, "
    + "{4} face{5}, {6} triangle{7} and "
    + "{8} vertice{9} exported.",
    nElements, Util.PluralSuffix( nElements ),
    nSolids, Util.PluralSuffix( nSolids ),
    nFaces, Util.PluralSuffix( nFaces ),
    nTriangles, Util.PluralSuffix( nTriangles ),
    nVertices, Util.PluralSuffix( nVertices ) );
 
  InfoMsg( msg );
}

Exporter Mainline

The external command mainline sets up a filtered element collector to define all elements to be exported.

It supports pre-selecting specific elements, in which case only those are used.

Even when limiting the filtered element collector to a predefined set, at least one filter must still be applied, or the filtered element collector will throw an exception.

I chose to apply the WhereElementIsNotElementType and WhereElementIsViewIndependent in all cases.

The user is prompted to select an output file, the exporter is instantiated, and the job is done:

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;
 
  // Determine elements to export
 
  FilteredElementCollector collector = null;
 
  // Access current selection
 
  SelElementSet set = uidoc.Selection.Elements;
 
  int n = set.Size;
 
  if( 0 < n )
  {
    // If any elements were preselected,
    // export those to OBJ
 
    ICollection<ElementId> ids = set
      .Cast<Element>()
      .Select<Element, ElementId>( e => e.Id )
      .ToArray<ElementId>();
 
    collector = new FilteredElementCollector( doc, ids );
  }
  else
  {
    // If nothing was preselected, export 
    // all model elements to OBJ
 
    collector = new FilteredElementCollector( doc );
  }
 
  collector.WhereElementIsNotElementType()
      .WhereElementIsViewIndependent();
 
  if( null == _export_folder_name )
  {
    _export_folder_name = Path.GetTempPath();
  }
 
  string filename = null;
 
  if( !FileSelect( _export_folder_name, 
    out filename ) )
  {
    return Result.Cancelled;
  }
 
  _export_folder_name 
    = Path.GetDirectoryName( filename );
 
  ObjExporter exporter = new ObjExporter();
 
  Options opt = app.Create.NewGeometryOptions();
 
  ExportElements( exporter, collector, opt );
 
  exporter.ExportTo( filename );
 
  return Result.Succeeded;
}

Export Results

Here is the result of exporting a single wall. It is actually one of the end walls in the standard Revit sample project rac_advanced_sample_project.rvt:

Here are the resulting object counts of resulting elements, faces, triangles, etc.:

Running the same command without preselecting anything exports the entire model. Again, using rac_advanced_sample_project.rvt, the result looks like this:

The following object counts are reported in this case:

The resulting OBJ file sample_model.obj is 5 MB in size, which is pretty tolerable considering all faces are completely triangulated.

As you can see in both of these cases, the number of faces is significantly higher than the number of vertices. Just imagine what the number of vertices and resulting file size would be like if I had not gone to the effort of eliminating duplicate vertices. The vertex count would simply have been three times the triangle count in both cases, i.e. 82 * 3 = 246 instead of 43, a factor of 5.72, and 163964 * 3 = 491892 instead of 86527, a factor of 5.68.

OBJ Model Export Considerations

As I already said, I am getting going with the cloud, and my first project is to export a Revit model to the Wavefront OBJ file format, which seems to be pretty standard and compact.

My exploration so far led to a number of observations and other issues:

• Cloud and mobile DevBlog
• Selecting model elements
• OBJ file format
• Eliminating duplicate vertices
• XYZ vertex lookup
• Integer-based vertex lookup
• Next steps

Cloud and Mobile DevBlog

Talking about cloud and mobile, we have another addition to our growing list of ADN DevBlogs:

The Cloud and Mobile Development DevBlog has now been launched.

For more background information on it and an overview of the other ADN DevBlogs, please refer to Kean's announcement.

Selecting Model Elements

Before we can start exporting the Revit model geometry, we need to determine which elements to extract the data from.

We took a couple of stabs at this in the past; an early one was for Revit 2010 (revisited), selecting each element that:

• Is not a family or a family symbol
• Has a valid category
• Has non-empty geometry

This proved to be too simple, and further tests were required to eliminate unwanted elements.

We revisited the topic using filtered element collectors to retrieve all model elements in Revit 2011 (updated).

Here are some other possible criteria to apply besides the three listed above:

• Category HasMaterialQuantities property
• FilteredElementCollector WhereElementIsNotElementType and WhereElementIsViewIndependent methods

You may also find that you need to define detailed lists of categories or other criteria to satisfy for your specific requirements in selecting the elements to export.

OBJ File Format

Back to the OBJ format, one of its main advantages is its extremely succinct file format specification. As you can see, the only data that absolutely needs to be specified is the vertices and faces. Optionally, texture coordinates and normals can also be defined. The slightly more extensive Wikipedia version also explains how parameter space vertices can be specified, and how colours are defined using a material library.

Here is a sample OBJ file cube.obj representing a cube and a material library material.mtl that I found in the .obj Loader for Android distribution.

The cube definition is rather sub-optimal, though, listing and making use of 24 vertices, although we all know that a cube only has a total of eight corners. Here is an optimised OBJ representation of a cube:

v 1 1 1
v 1 1 -1
v 1 -1 1
v 1 -1 -1
v -1 1 1
v -1 1 -1
v -1 -1 1
v -1 -1 -1
f 1 3 4 2
f 5 7 8 6
f 1 5 6 2
f 3 7 8 4
f 1 5 7 3
f 2 6 8 4

Eliminating Duplicate Vertices

As the trivial example above shows, you can significantly reduce the size of an OBJ by eliminating duplicate vertex definitions. The generator of the larger cube sample file above defined 24 points, i.e. 4 * 6. It probably simply iterated over all six cube faces and output a new vertex definition for each face corner encountered, regardless of repetition.

This is very wasteful. In Revit it also incurs the additional risk of defining vertices which are supposed to specify corners of adjacent faces, but may be slightly off, as we discussed in obtaining the top faces of sloped walls, retrieving unique geometry vertices from a selected element, and most recently in the geometry traversal to retrieve unique vertices from concrete structural elements.

If we collect all unique vertices in the Revit model and use the resulting list to avoid any duplicate definitions in the OBJ file, we can drastically reduce the number of vertex definitions, in this case from 24 to 8, and improve precision at the same time.

XYZ Vertex Lookup

According to the observations above, I implemented a vertex lookup class providing a method AddVertex taking an XYZ input argument specifying a new triangle vertex to store for exporting.

It looks up the given XYZ point and either returns the index of a previously defined point, if possible, or creates a new entry for it and returns that index.

As discussed so many times in the past, the point comparison has to include some fuzz.

Here is the full implementation of my VertexLookupXyz class with its own built-in XyzEqualityComparer:

/// <summary>
/// A vertex lookup class to eliminate duplicate 
/// vertex definitions
/// </summary>
class VertexLookupXyz : Dictionary<XYZ, int>
{
  #region XyzEqualityComparer
  /// <summary>
  /// Define equality for Revit XYZ points.
  /// Very rough tolerance, as used by Revit itself.
  /// </summary>
  class XyzEqualityComparer : IEqualityComparer<XYZ>
  {
    const double _sixteenthInchInFeet
      = 1.0 / ( 16.0 * 12.0 );
 
    public bool Equals( XYZ p, XYZ q )
    {
      return p.IsAlmostEqualTo( q,
        _sixteenthInchInFeet );
    }
 
    public int GetHashCode( XYZ p )
    {
      return Util.PointString( p ).GetHashCode();
    }
  }
  #endregion // XyzEqualityComparer
 
  public VertexLookupXyz()
    : base( new XyzEqualityComparer() )
  {
  }

  /// <summary>
  /// Return the index of the given vertex,
  /// adding a new entry if required.
  /// </summary>
  public int AddVertex( XYZ p )
  {
    return ContainsKey( p )
      ? this[p]
      : this[p] = Count;
  }
}

The XYZ points that I consider here are in the original Revit model coordinate system, i.e. in feet.

Integer-based Vertex Lookup

Thinking about the issue a bit further, though, I discovered several enhancement possibilities.

On one hand, it might be more useful for me to create the OBJ files in millimetres instead of feet.

Secondly, if you don't require floating-point precision, using integers is always more efficient, and mostly simpler as well.

This led me to define my own integer-based point class for storing the vertex coordinates in millimetres instead of feet, and in whole numbers instead of floating point.

The rest of my algorithm remained completely unchanged, and the resulting OBJ file also only differed in the actual vertex coordinate values.

Here is the implementation of my VertexLookupInt class with its own built-in integer based point class PointInt and PointIntEqualityComparer:

class PointInt : IComparable<PointInt>
{
  public int X { get; set; }
  public int Y { get; set; }
  public int Z { get; set; }
 
  const double _feet_to_mm = 25.4 * 12;
 
  static int ConvertFeetToMillimetres( double d )
  {
    return (int) ( _feet_to_mm * d + 0.5 );
  }
 
  public PointInt( XYZ p )
  {
    X = ConvertFeetToMillimetres( p.X );
    Y = ConvertFeetToMillimetres( p.Y );
    Z = ConvertFeetToMillimetres( p.Z );
  }
 
  public int CompareTo( PointInt a )
  {
    int d = X - a.X;
 
    if( 0 == d )
    {
      d = Y - a.Y;
 
      if( 0 == d )
      {
        d = Z - a.Z;
      }
    }
    return d;
  }
}
 
/// <summary>
/// A vertex lookup class to eliminate duplicate 
/// vertex definitions
/// </summary>
class VertexLookupInt : Dictionary<PointInt, int>
{
  #region PointIntEqualityComparer
  /// <summary>
  /// Define equality for integer-based PointInt.
  /// </summary>
  class PointIntEqualityComparer : IEqualityComparer<PointInt>
  {
    public bool Equals( PointInt p, PointInt q )
    {
      return 0 == p.CompareTo( q );
    }
 
    public int GetHashCode( PointInt p )
    {
      return (p.X.ToString() 
        + "," + p.Y.ToString() 
        + "," + p.Z.ToString())
        .GetHashCode();
    }
  }
  #endregion // PointIntEqualityComparer
 
  public VertexLookupInt()
    : base( new PointIntEqualityComparer() )
  {
  }

  /// <summary>
  /// Return the index of the given vertex,
  /// adding a new entry if required.
  /// </summary>
  public int AddVertex( PointInt p )
  {
    return ContainsKey( p )
      ? this[p]
      : this[p] = Count;
  }
}

Next steps

I would dearly love to complete the entire discussion right here and now, but I guess that is enough for one go.

Here is an example of how far I have come with my implementation so far, exporting the rac_advanced_sample_project.rvt to OBJ and viewing it in a Windows-based mesh viewer, still in mono-chrome, I'm afraid:

Here are some of the next steps I plan to take in the coming days:

• Discuss the rest of the OBJ export implementation in its current state
• Add support for colour
• Upload to the cloud
• View on mobile device

It will be interesting to see where this leads us. As always, feedback and suggestions are more than welcome.

Real-World Concrete Corner Coordinates

I mentioned that I worked together with Paul Hellawell of GHD on a full-blown end-user-capable little application for the automatic creation of setout points for on-site location and construction of structural elements at the Melbourne DevLab.

Paul provided a description of the task and the initial idea for an implementation approach.

We got the application to a useful working state in the two days during the DevLab, and Paul has provided it to his designers to use in real projects ever since.

Before we look at the full-fledged application, let's explore the core API functionality required:

• Filtering for structural concrete elements.
• Retrieving their corners, i.e. geometry traversal to retrieve unique vertices.
• Converting from Revit model to real-world coordinates.

Once this is all in place, we can explain how to use the core functionality to implement the real-world end-user application.

Filtering for Structural Concrete Elements

We already looked at retrieving structural elements.

Just like there, we check for certain specific classes like Wall and Floor, and also for generic family instances with categories from our list of interest, including structural columns, framing, foundation, floors and ramps.

In this case, we are only interested in concrete elements, so we apply two structural material type filters as well, for concrete and precast concrete.

This is the method we ended up with to suit our purposes:

/// <summary>
/// Retrieve all structural elements that we are 
/// interested in using to define setout points.
/// We are looking at concrete for the moment.
/// This includes: columns, framing, floors, 
/// foundations, ramps, walls. 
/// </summary>
FilteredElementCollector GetStructuralElements(
  Document doc )
{
  // What categories of family instances
  // are we interested in?
 
  BuiltInCategory[] bics = new BuiltInCategory[] {
    BuiltInCategory.OST_StructuralColumns,
    BuiltInCategory.OST_StructuralFraming,
    BuiltInCategory.OST_StructuralFoundation,
    BuiltInCategory.OST_Floors,
    BuiltInCategory.OST_Ramps
  };
 
  IList<ElementFilter> a
    = new List<ElementFilter>( bics.Length );
 
  foreach( BuiltInCategory bic in bics )
  {
    a.Add( new ElementCategoryFilter( bic ) );
  }
 
  LogicalOrFilter categoryFilter
    = new LogicalOrFilter( a );
 
  // Filter only for structural family 
  // instances using concrete or precast 
  // concrete structural material:
 
  List<ElementFilter> b
    = new List<ElementFilter>( 2 );
 
  b.Add( new StructuralMaterialTypeFilter( 
    StructuralMaterialType.Concrete ) );
 
  b.Add( new StructuralMaterialTypeFilter( 
    StructuralMaterialType.PrecastConcrete ) );
 
  LogicalOrFilter structuralMaterialFilter 
    = new LogicalOrFilter( b );
 
  List<ElementFilter> c
    = new List<ElementFilter>( 3 );
 
  c.Add( new ElementClassFilter( 
    typeof( FamilyInstance ) ) );
 
  c.Add( structuralMaterialFilter );
  c.Add( categoryFilter );
 
  LogicalAndFilter familyInstanceFilter
    = new LogicalAndFilter( c );
 
  IList<ElementFilter> d
    = new List<ElementFilter>( 6 );
 
  d.Add( new ElementClassFilter(
    typeof( Wall ) ) );
 
  d.Add( new ElementClassFilter(
    typeof( Floor ) ) );
 
  //d.Add( new ElementClassFilter(
  //  typeof( ContFooting ) ) );
 
#if NEED_LOADS
  d.Add( new ElementClassFilter(
    typeof( PointLoad ) ) );
 
  d.Add( new ElementClassFilter(
    typeof( LineLoad ) ) );
 
  d.Add( new ElementClassFilter(
    typeof( AreaLoad ) ) );
#endif
 
  d.Add( familyInstanceFilter );
 
  LogicalOrFilter classFilter
    = new LogicalOrFilter( d );
 
  FilteredElementCollector col
    = new FilteredElementCollector( doc )
      .WhereElementIsNotElementType()
      .WherePasses( classFilter );
 
  return col;
}

Geometry Traversal to Retrieve Unique Vertices

Once the required elements have been retrieved, we analyse their geometry to determine all corners, i.e. geometry vertices.

This goes back to the second day of the Melbourne Revit API training, where we looked at retrieving unique geometry vertices from a selected element.

This involves comparing XYZ points, i.e. real number equality testing.

First of all, we need an equality comparer for points:

/// <summary>
/// Define equality for Revit XYZ points.
/// Very rough tolerance, as used by Revit itself.
/// </summary>
class XyzEqualityComparer : IEqualityComparer<XYZ>
{
  const double _sixteenthInchInFeet 
    = 1.0 / ( 16.0 * 12.0 );
 
  public bool Equals( XYZ p, XYZ q )
  {
    return p.IsAlmostEqualTo( q, 
      _sixteenthInchInFeet );
  }
 
  public int GetHashCode( XYZ p )
  {
    return PointString( p ).GetHashCode();
  }
}

With that in hand, we can retrieve all unique vertices of a given solid retrieved from the element geometry:

/// <summary>
/// Return all the "corner" vertices of a given solid.
/// Note that a circle in Revit consists of two arcs
/// and will return a "corner" at each of the two arc
/// end points.
/// </summary>
Dictionary<XYZ,int> GetCorners( Solid solid )
{
  Dictionary<XYZ, int> corners 
    = new Dictionary<XYZ, int>( 
      new XyzEqualityComparer() );
 
  foreach( Face f in solid.Faces )
  {
    foreach( EdgeArray ea in f.EdgeLoops )
    {
      foreach( Edge e in ea )
      {
        XYZ p = e.AsCurveFollowingFace( f )
          .get_EndPoint( 0 );
 
        if( !corners.ContainsKey( p ) )
        {
          corners[p] = 0;
        }
        ++corners[p];
      }
    }
  }
  return corners;
}

The solid is retrieved by traversing the element geometry and picking the first non-empty one found.

Special handling is required for family instances, of course, since they have an additional transformation that we have to take account of. The family definition defines its own local coordinate system, and we need to transform the solid from that to the Revit model space.

This implementation processes all the cases we have run into so far correctly and elegantly:

/// <summary>
/// Retrieve the first non-empty solid found for 
/// the given element. In case the element is a 
/// family instance, it may have its own non-empty
/// solid, in which case we use that. Otherwise we 
/// search the symbol geometry. If we use the 
/// symbol geometry, we have to keep track of the 
/// instance transform to map it to the actual
/// instance project location.
/// </summary>
Solid GetSolid( Element e, Options opt )
{
  GeometryElement geo = e.get_Geometry( opt );
 
  Solid solid = null;
  GeometryInstance inst = null;
  Transform t = Transform.Identity;
 
  // Some columns have no solids, and we have to 
  // retrieve the geometry from the symbol; 
  // others do have solids on the instance itself 
  // and no contents in the instance geometry 
  // (e.g. in rst_basic_sample_project.rvt).
 
  foreach( GeometryObject obj in geo )
  {
    solid = obj as Solid;
 
    if( null != solid
      && 0 < solid.Faces.Size )
    {
      break;
    }
 
    inst = obj as GeometryInstance;
  }
 
  if( null == solid && null != inst )
  {
    geo = inst.GetSymbolGeometry();
    t = inst.Transform;
 
    foreach( GeometryObject obj in geo )
    {
      solid = obj as Solid;
 
      if( null != solid
        && 0 < solid.Faces.Size )
      {
        break;
      }
    }
  }
  return solid;
}

Transforming Revit Model Coordinates to the Real World

After the solid vertices have been retrieved in Revit model space, we convert them to real-world coordinates using the project location.

We initially tried to achieve this piecewise by fiddling with the base point offset and manually rotating to project north. This was both complicated and returned incorrect results.

The correct solution is very simple and was already discussed a couple of times in the past:

• Transformations
• Project location
• Transformed family instance geometry

This led us to implement the following GetProjectLocationTransform method:

/// <summary>
/// Return the project location transform.
/// </summary>
Transform GetProjectLocationTransform( Document doc )
{
  // Retrieve the active project location position.
 
  ProjectPosition projectPosition
    = doc.ActiveProjectLocation.get_ProjectPosition(
      XYZ.Zero );
 
  // Create a translation vector for the offsets
 
  XYZ translationVector = new XYZ(
    projectPosition.EastWest,
    projectPosition.NorthSouth,
    projectPosition.Elevation );
 
  Transform translationTransform
    = Transform.get_Translation(
      translationVector );
 
  // Create a rotation for the angle about true north
 
  Transform rotationTransform 
    = Transform.get_Rotation( XYZ.Zero, 
      XYZ.BasisZ, projectPosition.Angle );
 
  // Combine the transforms 
 
  Transform finalTransform
    = translationTransform.Multiply(
      rotationTransform );
 
  return finalTransform;
}

Making use of the resulting transform later is trivial:

  Transform projectLocationTransform 
    = GetProjectLocationTransform( doc );
 
  for each concrete corner point XYZ p:
  {
    // Transform insertion point by applying
    // project location transformation.
 
    XYZ r2 = projectLocationTransform.OfPoint( p );
  }

Now I just need to find some more time to discuss how this can all be put together and wrapped into a useful real-world end-user application.

DevCamp Day Two

This morning I presented my second session, on some of the Revit 2013 UI API enhancements, in the Revit API beginner track. After that, I returned back to the Revit API expert one to attend the presentations on modeless interaction and IFC before presenting my final session on the Revit MEP API. Here then are my sessions of today, in chronological order:

• 1-4 Revit 2013 UI API enhancements
• 2-3 Asynchronous interactions
• 2-2 IFC export open source
• 2-7 Revit MEP API

Revit 2013 UI API Enhancements

Enhanced add-in integration is an important topic in the Revit 2013 API. This session discusses four of the add-in integration topics in more depth, building on a preceding presentation by Saikat Bhattacharya presenting a snapshot of the entire Revit UI API functionality:

• Revit progress bar notifications
• Options dialogue WPF custom extensions
• Embed and control a Revit view
• Drag and drop

All four of these are covered by existing SDK samples, the first by ProgressNotifier (Events), the others by the comprehensive UIAPI sample.

For someone like me, feeling a strong affinity to Winnie the Pooh, the "bear of very little brain", the existing SDK samples are way beyond simple comprehension and reuse, so I ended up creating four own extremely simple and minimal ones exercising these features in just a few lines of code each instead, to reduce the code and required audience comprehension power to an absolute minimum.

Revit progress bar notifications

To receive information about the current Revit progress bar status, you can subscribe to the ProgressChanged event.

The event handler will receive a ProgressChangedEventArgs instance providing the following properties:

• Caption – progress bar caption describing operation in progress
• Stage – current stage of the progress bar, one of Started, CaptionChanged, RangeChanged, PositionChanged, UserCancelled, Finished
• LowerRange – lower limit of range, always zero
• UpperRange – upper limit of range, any non-zero number
• Position – Value between zero and UpperRange incremented with "PositionChanged" stage

The ProgressNotifier SDK sample displays a WPF-based dialogue box. It provides a button to open and load a Revit model. Loading the selected file will cause a number of progress bar actions to execute. These actions are monitored and presented in a stack structure, since occasionally more than one progress bar event may be active simultaneously:

My new ProgressWatcher sample in much simpler and tracks all progress bar events by just printing the event argument data to the Visual Studio debug output window. This can be achieved in a very few lines of code, basically only one each to subscribe to the event and to access and print the progress bar event data:

[Transaction( TransactionMode.ReadOnly )]
public class Command : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    Application app = uiapp.Application;
 
    app.ProgressChanged 
      += new EventHandler<ProgressChangedEventArgs>( 
        OnProgressChanged );
 
    return Result.Succeeded;
  }
 
  void OnProgressChanged( 
    object sender, 
    ProgressChangedEventArgs e )
  {
    double percent = 100.0 * e.Position / e.UpperRange;
 
    Debug.Print( 
      "'{0}' stage {1} position {2} [{3}, {4}] ({5}%)",
      e.Caption, e.Stage, e.Position, e.LowerRange, 
      e.UpperRange, percent.ToString( "0.##" ) );
  }
}

Saving the output to a text file will allow you to analyse in detail the progress bar event sequence and nesting.

Options dialogue WPF custom extensions

In Revit 2013, an add-in can add its own custom tabs to the standard Revit Options dialogue.

This is achieved by defining a WPF control to display and subscribing to the UIApplication DisplayingOptionsDialog event.

The event handler receives an DisplayingOptionsDialogEventArgs instance. It has a PagesCount property providing the number of Options dialogue tabs including default Revit ones. It also sports the AddTab method that can be used to add a tab, providing a name and a handler for it. The handler information is encapsulated in the TabbedDialogExtension class.

The TabbedDialogExtension class provides a constructor taking two arguments, a WPF user control instance and an OK handler. These cannot be changed later. It provides methods to get and set contextual help, and properties to read the WPF control and OK handler. It also provides properties to both get and set the cancel and 'restore defaults' handlers:

• Control – the control
• OnOKAction – the ok handler
• OnCancelAction – the cancel handler
• OnRestoreDefaultsAction – the restore defaults handler

The UIAPI SDK sample adds several custom tabs demonstrating most available features.

I created a minimal sample named AddOptionsTab which defines the simplest possible WPF control with one single button to click:

If you click the button, the corresponding event handler on the form is called, which simply displays a task dialog:

If this tab has ever been activated after the Options dialogue was opened, its OK, cancel and 'restore defaults' handlers are called, depending on the user actions.

Here is the entire user control source code defining its handlers:

public partial class UserControl1 : UserControl
{
  string _name;
 
  public UserControl1( string name )
  {
    _name = name;
 
    InitializeComponent();
  }
 
  private void button1_Click( 
    object sender, 
    RoutedEventArgs e )
  {
    TaskDialog.Show( _name, "I was clicked..." );
  }
 
  public void OnOK()
  {
    TaskDialog.Show( _name, "OK" );
  }
 
  public void OnCancel()
  {
    TaskDialog.Show( _name, "OnCancel" );
  }
 
  public void OnRestoreDefaults()
  {
    TaskDialog.Show( _name, "OnRestoreDefaults" );
  }
}

The event handler code reacting to the Options dialogue displaying simply instantiates the user control, calls the TabbedDialogExtension constructor with it, and feeds that to the event handler arguments AddTab method:

void OnDisplayingOptionsDialog( 
  object sender, 
  DisplayingOptionsDialogEventArgs e )
{
  UserControl1 c = new UserControl1( 
    "DevCamp User Control" );
 
  e.AddTab( "DevCamp Custom Tab", 
    new TabbedDialogExtension( 
      c, c.OnOK ) );
}

The event handler is called each time the Options dialogue is invoked once the event has been subscribed to, which is achieved in a single line of code like this in the AddOptionsTab external command:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
 
  uiapp.DisplayingOptionsDialog 
    += new EventHandler<DisplayingOptionsDialogEventArgs>( 
      OnDisplayingOptionsDialog );
 
  return Result.Succeeded;
}

Embed and control a Revit view

Another of the add-in integration enhancements enables you to embed and control a Revit view in your own form, dialogue or window.

The new PreviewControl class presents a preview control to browse the Revit model. It takes two input arguments, a document and a view id. The hosting form or window must be modal. The View can be any graphical view, i.e. must be printable. Perspective views are also supported, and all 3D Views can be manipulated by view cube. The visibility and graphical settings of the view are effective and respected by the control.

The UIAPI SDK sample proves a demonstration of this as well, which allows you to interactively select any of the open documents to view, or even open a new one, and secondly presents a list of all the documents views for you to switch between. Each time you change any of these two selections, the current preview control is discarded and a new one is instantiated with the updated input arguments. These input arguments are the only way in which the add-in affects the view, all further interaction happens between the control and the user.

To use a Revit preview control, you simply create a standard .NET form and insert a WPF host in it. A suitable host is the System.Windows.Forms.Integration.ElementHost. You populate this with a new Revit preview control instance, e.g. like this

  elementHost.Child = new PreviewControl( 
    doc, view.Id );

The PreviewControl instance needs to be disposed of after use:

  PreviewControl vc = elementHost.Child
    as PreviewControl;

  if( vc != null ) { vc.Dispose(); }

Here is a code snippet showing how all the printable views can be retrieved using a filtered element collector:

  IEnumerable<View> views
    = new FilteredElementCollector( doc )
      .OfClass( typeof( View ) )
      .Cast<View>()
      .Where<View>( v => v.CanBePrinted );

I created a minimal sample application PreviewControlSimple for this DevCamp class with much less code (and functionality than the UIAPI one, since it just displays the current view of a document with no further ado.

It does add one interesting twist, though: to show exactly how the hosting form is set up, I implemented that twice over, first using the Visual Studio designer as usual, and then converting the form to be completely programmatically generated. Here is the DisplayRevitView method taking the document and view input arguments for the preview control. It also takes a third argument for the main Revit window, so that the generated control can be hooked up to that as a parent window. This defines an appropriate relationship between the two as far as the Windows OS is concerned, ensuring correct minimisation and restoration behaviour:

const string _caption_prefix
  = "Simple Revit Preview - ";
 
void DisplayRevitView( 
  Document doc,
  View view,
  IWin32Window owner )
{
 
  using( PreviewControl pc
    = new PreviewControl( doc, view.Id ) )
  {
 
#if CREATE_FORM_BY_CODE
 
    using( System.Windows.Forms.Form form
      = new System.Windows.Forms.Form() )
    {
      ElementHost elementHost = new ElementHost();
 
      elementHost.Location
        = new System.Drawing.Point( 0, 0 );
 
      elementHost.Dock = DockStyle.Fill;
      elementHost.TabIndex = 0;
      elementHost.Parent = form;
      elementHost.Child = pc;
 
      form.Text = _caption_prefix + view.Name;
      form.Controls.Add( elementHost );
      form.Size = new Size( 400, 400 );
      form.ShowDialog( owner );
    }
 
#else // if not CREATE_FORM_BY_CODE
 
    Form1 form = new Form1( pc );
    form.ShowDialog( owner );
 
#endif // CREATE_FORM_BY_CODE
 
  }
}

Please note that correct disposal of the preview control is ensured by the 'using' statement. This is similar to Arnošt's strong recommendation to always encapsulate Revit Transactions in a 'using' statement.

Calling this method from the external command mainline with the current document view is trivial. I add one line of code to access the Revit main window:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  IWin32Window revit_window
    = new JtWindowHandle(
      ComponentManager.ApplicationWindow );
 
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Document doc = uidoc.Document;
 
  View view = doc.ActiveView;
 
  DisplayRevitView( doc, view, revit_window );
 
  return Result.Succeeded;
}

Drag and Drop API

I recently discussed the new drag and drop functionality and the UIAPI sample command demonstrating it.

The UIApplication provides the new static DoDragDrop method, with two overloads:

• DoDragDrop( ICollection<string> ) – initiate a standard built-in Revit drag and drop operation taking a collection of file names.
• DoDragDrop( object, IDropHandler ) – initiate a drag and drop operation with a custom drop implementation.

This method is designed for use in a modeless form.

Please note that this is currently the one and only Revit API method not requiring a valid Revit API context.

This method can be called from your modeless form at any time, even without Revit giving you explicit permission to interact with the API via some form of callback or notification, as required for all other Revit API calls.

The behaviour of drag and drop given a list of filenames depends on the type of files, as I already recently pointed out:

• One AutoCAD format or image file dragged onto Revit – A new import placement editor is started to import the file.
• More than one AutoCAD format or image files dragged – A new import placement editor is started for the first file.
• One family file dragged onto Revit – The family is loaded, and an editor started to place an instance.
• More than one family file dragged onto Revit – All the families are loaded.
• More than one family file including other format files dragged – Revit tries to open all the files.
• Valid file or list of files is passed – Revit does its best to use them appropriately.
• Any files are not usable – Failure is signalled to user, no exception is thrown, add-in is not notified.

Here again, I implemented a new DevCamp sample add-in DragDropApi to be able to show the necessary steps in a simpler context than the corresponding UIAPI example.

Here are my four new Revit 2013 UI API samples AddOptionsTab, DragDropApi, PreviewControlSimple, ProgressWatcher and the slides I used.

Asynchronous Interactions

Arnošt Löbel already presented on this topic at Autodesk University 2011 in his class CP5381 'Asynchronous Interactions and Managing Modeless UI with the Autodesk Revit API', as mentioned in the overview of the AU 2011 Revit and AEC API sessions.

In this class, Arnošt also covered the new external events and demonstrated his ModelessForm_ExternalEvent, ModelessForm_IdlingEvent (ModelessDialog) and WorkThread (MultiThreading) SDK samples.

The conclusion of the presentation is the following pledge that we are all strongly recommended to take:

• I shall not call the API unless invoked by it
• I shall not call the API from anywhere but the main thread
• I shall call the API only, not directly the Revits UI
• I shall use the Idling event cautiously and considerably

Here is a snapshot of the entire slide deck. This is not the final version, which will be posted soon after the end of DevCamp.

IFC Export Open Source

Angel Velez is senior principal engineer in the Revit development team and presented on the IFC exporter open source project, covering the following main topics:

• Introduction
  • History of IFC in Revit
  • Why open source?
• How the code Works
  • Overall structure of code
  • Key points of interest, e.g. element traversal, property sets
  • Look at alternate UI

Here is the snapshot of his slides.

Revit MEP API

The Revit MEP API is a recurring topic of mine at Autodesk University, and I presented on this once again last year in my session CP4453 'Everything in Place with Autodesk Revit MEP Programming', as mentioned in the overview of the AU 2011 Revit and AEC API sessions. The AU materials and the sample code that I use there was already published and discussed.

In preparation for the sessions here in Waltham, I also discussed the Revit 2013 MEP API and completed the migration of the ADN MEP sample code to Revit 2013.

Here is the slide deck I used today, based on the AU one and updated for Revit MEP 2013.

Please note again that all the materials provided above are just snapshots. Soon after the conference completes, the complete and final materials will be published.

Winding Down and Winding Up Again

In the evening we went out for a DevTech dinner, Japanese and Chinese cuisine. It was great to hang out with the guys for a while and wind down a bit:

Next stop is the DevLab tomorrow with a record number of almost fifty registered participants, so we will be way busy! Time to wind up again. No rest for the wicked! These events are always great, and I'm looking forward to it a lot.