The Building Coder

Vertical Projection of Beam Analytical Model

We tried to fly from Milano to Paris this evening for the last DevDays conference, but unfortunately our flight was cancelled due to snow in Paris. Now we are stuck at the Milano airport and hoping that the first flight in the morning will not be cancelled as well. If it is, we will not be able to make it at all. Otherwise, we will arrive rather late and have to reschedule the agenda, but at least then we will not be forced to cancel the whole conference. Fervently hoping for the best...

Since I am not sleeping anyway, I may as well post.

First, here are some more titbits from AU:

Kean posted an AU wrap-up with a short video and some snapshots from various Autodesk University experiences.

As part of AUv, Jim Quanci gave a very informative virtual interview on the Autodesk Developer Network ADN which is the part of Autodesk that provides developer support and that I work in. It has now been posted on the AU YouTube channel and...

• Provides an overview of and helps better understand the ADN.
• Shows the wide variety of applications being created by our partners.
• Describes the benefits of being a member of the network.
• Raises interest in ADN and our partners.

Getting back to the Revit API, here is a recent case handled by my colleagues Joe Ye and Saikat Bhattacharya which shows how to handle the setting of the vertical projection of the analytical model of a beam. An interesting aspect of this is that the parameter data type is an element id, and yet we are actually storing an enumeration value in it. This is not uncommon in Revit parameters; there are a few of them that can take both element ids to refer to other database objects as well as a fixed set of enumeration values for specific exceptional cases.

Question: How can I set the 'Vertical Projection' parameter of a beam to the 'Center of Beam' value?"

Answer: Here is a description on how to set the vertical projection parameter of a beam.

Start by defining the following enumeration:

enum AnalyticalVerticalProjection_e
{
  AVP_AUTODETECT = -1,
  AVP_TOP_OF_PHYSICAL = -2,
  AVP_CENTER_OF_PHYSICAL = -3,
  AVP_BOTTOM_OF_PHYSICAL = -4,
};

This can be used as follows:

• Construct an ElementId object, for instance, id.
• Set id.Value to one of the enumeration member values.
• Set the vertical projection parameter value to id.

Note that the parameter value can be set successfully to the value, even though it is not a real element id.

Here is a code snippet showing how to set value to top of the slab:

Element e = SelectSlab( "Please select a slab", 
  commandData, typeof( Floor ) );
 
if( null != e )
{
  Floor floor = e as Floor;
 
  BuiltInParameter bip = BuiltInParameter
    .STRUCTURAL_ANALYTICAL_PROJECT_FLOOR_PLANE;
 
  Parameter p = floor.get_Parameter( bip );
 
  ElementId id = p.AsElementId();
 
  // id.Value is negative if the parameter 
  // value is not a real element id:
 
  id.Value = -2; // top of the slab
 
  p.Set( ref id );
}

Thank you Joe and Saikat for this illuminating answer!

Crop 3D View to Room

In case you have heard enough about both climbing and AU and AUv in the last few posts and would prefer to read about the Revit API and nothing but the Revit API, here is something for you. This is based on a recent case handled by Joe Ye and deals with the 3D view crop box and the transformations required to set it up properly, an issue we have never previously looked at.

Question: I would like to set the crop box of a 3D view to correspond to a single room.

Answer: As the 3D view rotates the room, the original bounding box of the plan view will not be suitable to use for the 3D view crop box. Here is an idea to calculate the crop box. Retrieve all the corner point vertex coordinates of the room, and project them onto the plane perpendicular to the 3D view's view direction. This produces projected point coordinates. From these result point coordinates, determine the maximum and minimum X and Y values. From the max and min points, create the 3D view's crop box.

Here are the detailed steps to implement this idea:

• Retrieve all vertex coordinates of the room.
• Project these coordinates to the plane perpendicular to the 3D view's view direction. To do so, create a face perpendicular to the view direction. The projected results can be obtained from the Face.Project method taking an XYZ point argument. For more information, see the Revit API help file RevitAPI.chm for the usage and return value of this method.
• Go through the resulting coordinates and determine the maximum and minimum X and Y coordinate values.
• Use the four values to determine a bounding box:

  BoundingBoxXYZ bb = new BoundingBoxXYZ(); 
  bb.Min = NewXYZ( xMin, yMin, 0 );
  bb.Max = NewXYZ( xMax, yMax, 0 );
  

• Use the bounding box to set the 3D view crop box:

  View3d.CropBox = bb;
  

Actually, after some further investigation, I found a better way to determine the room extents. It is hard to create a solid and make one face of it perpendicular to the view direction.

You can also use the Transform class to calculate the crop box of the 3D view instead.

First, determine the transformation for translating coordinates in the 3D view to the world coordinate system WCS from the View3d.CropBox.Transform property. Then invert it to obtain the transformation to translate model WCS coordinates back to the 3D view coordinates.

Determine the room vertices from its ClosedShell property, and translate them to 3D view coordinates. Find the minimum and maximum X and Y coordinate values as described above and set the 3D view's crop box Max and Min properties using these.

You do need to activate and make the crop box visible to see the effect. You can do so using the Crop View and Show Crop Region buttons in the user interface:

This can also be achieved programmatically using:

  view3d.CropBoxActive = true;
  view3d.CropBoxVisible = true;

So far for Joe's idea. Many thanks to Joe for all the research into this!

I implemented a new Building Coder sample command CmdCropToRoom to test and demonstrate this. In order to show how the crop box can be set to various different regions in the model, it iterates over all the rooms in the model and sets the crop box of the current 3D view to the next room in the sequence on each call. We retrieve a list of all rooms in the model using doc.get_Elements:

List<RvtElement> rooms = new List<RvtElement>();
int n = doc.get_Elements( typeof( Room ), rooms );

To loop through the rooms in the model and step to the next room in the list on each invocation of the command, we use their index in the list of elements returned by this call. The last index used is stored in a static variable _i, and the method BumpRoomIndex is used to increment it by one on each call:

static int _i = -1;

static int BumpRoomIndex( int room_count )
{
  ++_i;
 
  if( _i >= room_count )
  {
    _i = 0;
  }
  return _i;
}

The next room to crop the view to is selected using

Room room = (0 < n) 
  ? rooms[BumpRoomIndex( n )] as Room 
  : null;

Here is the entire code of the CmdCropToRoom external command Execute method which crops the current 3D view to the next room extents:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
View3D view3d = doc.ActiveView as View3D;
 
if( null == view3d )
{
  message = "Please activate a 3D view"
    + " before running this command.";
 
  return CmdResult.Failed;
}
 
// get the 3d view crop box:
 
BoundingBoxXYZ bb = view3d.CropBox;
 
// get the transform from the current view 
// to the 3D model:
 
Transform transform = bb.Transform;
 
// get the transform from the 3D model 
// to the current view:
 
Transform transformInverse = transform.Inverse;
 
// get all rooms in the model:
 
List<RvtElement> rooms = new List<RvtElement>();
int n = doc.get_Elements( typeof( Room ), rooms );
 
Room room = (0 < n) 
  ? rooms[BumpRoomIndex( n )] as Room 
  : null;
 
if( null == room )
{
  message = "No room element found in project.";
  return CmdResult.Failed;
}
 
// collect all vertices of room closed shell 
// to determine its extents:
 
GeoElement e = room.ClosedShell;
XYZArray vertices = app.Create.NewXYZArray();
 
foreach( GeometryObject o in e.Objects )
{
  if( o is Solid )
  {
    // iterate over all the edges of all solids:
 
    Solid solid = o as Solid;
 
    foreach( Edge edge in solid.Edges )
    {
      foreach( XYZ p in edge.Tessellate() )
      {
        // collect all vertices, 
        // including duplicates:
 
        vertices.Append( p );
      }
    }
  }
}
 
XYZArray verticesIn3dView 
  = app.Create.NewXYZArray();
 
foreach( XYZ p in vertices )
{
  verticesIn3dView.Append( 
    transformInverse.OfPoint( p ) );
}
 
// ignore the Z coorindates and find the 
// min and max X and Y in the 3d view:
 
double xMin = 0, yMin = 0, xMax = 0, yMax = 0;
 
bool first = true;
foreach( XYZ p in verticesIn3dView )
{
  if( first )
  {
    xMin = p.X;
    yMin = p.Y;
    xMax = p.X;
    yMax = p.Y;
    first = false;
  }
  else
  {
    if( xMin > p.X )
      xMin = p.X;
    if( yMin > p.Y )
      yMin = p.Y;
    if( xMax < p.X )
      xMax = p.X;
    if( yMax < p.Y )
      yMax = p.Y;
  }
}
 
// grow the crop box by one twentieth of its 
// size to include the walls of the room:
 
double d = 0.05 * ( xMax - xMin );
xMin = xMin - d;
xMax = xMax + d;
 
d = 0.05 * ( yMax - yMin );
yMin = yMin - d;
yMax = yMax + d;
 
bb.Max = new XYZ( xMax, yMax, bb.Max.Z );
bb.Min = new XYZ( xMin, yMin, bb.Min.Z );
 
view3d.CropBox = bb;
 
// change the crop view setting manually or 
// programmatically to see the result:
 
view3d.CropBoxActive = true;
view3d.CropBoxVisible = true;
 
return CmdResult.Succeeded;

Here is a minimal model with two rooms to test this command:

Running the external command defined by CmdCropToRoom sets the 3D view crop box to the extents of the first room:

Running it another time increments the current room index and sets the 3D view crop box to its extents instead:

Here is version 1.1.0.56 of the complete Building Coder sample source code and Visual Studio solution including the new command.

There are a number of conceivable enhancements to this code. One of the most obvious would be to eliminate duplicate vertices before applying the inverse transformations and searching for the minimum and maximum coordinate values. We did implement some useful functionality for doing that with the XyzEqualityComparer class and GetVertices method in the nested instances geometry retrieval. It might also be possible to use generic collections such as List<XYZ> instead of XYZArray for the original and transformed vertices, and generic .NET functionality to apply the transformation and determine the max and min coordinate values. We left out such enhancements in this case for the sake of clarity, but if you have any suggestions to make, please feel free to do so.

Handle Category Name Change

Here is a little note I wrote sitting in Washington Dulles airport and did not get around to posting until now, to point out the importance of using language independent category comparisons:

Question: Apparently at least one category name changed in the German version of Revit from 2009 to 2010:

• Revit 2009: "Tragende Stützen"
• Revit 2010: "Tragwerksstützen"

We rely on category names for mapping purposes. In this case we discovered the change that was causing problems for us, but I am worried that there may be other similar changes that I also need to be aware of. Is there any way to use a language independent identifier that will never change? I very much hope to find a way to identify categories in a language independent fashion.

Answer: You can use the built-in category enumeration to make your code language independent when working with categories. We looked at this and related topics in the discussions on category comparison and later explored it further for the model element selection, which we recently enhanced to handle a set of multiple categories using a list of built-in category enumeration values stored in _bics_to_skip and the helper method SkipThisBic to compare them all with a given value from a candidate element.

Title Block of Sheet

Here is a question that crops up now and then in different variations, on how to access the title block information of a sheet:

Question: My drawing list routine exports various sheet view information to a spreadsheet. I would like to include the name of the title block family that is associated with the view. What is the best way to find it? Do I need to loop through family instances, and do a reverse lookup?

My snooping tool freaks out whenever I select a title block family from the list of family instances, so I don't know if the host of that family instance will tie it to the specific sheet view?

Answer: If your version of RvtMgdDbg fails to display some information that you are interested in, I suggest you debug it and fix the problem, e.g. start it in the debugger and add an exception handler to the offending code.

I am confused by your statement 'name of the title block family that is associated with the view'. Do you mean sheet instead of view? In general, each sheet has a title block associated with it, and then hosts multiple views.

To see which title block is added when I add a new sheet to the model, I use a technique to track all new elements added. This technique uses the Revit API introduction labs Lab 2-1 element lister. I create a file containing a list of all elements in the BIM before and after adding the sheet and then compare them. Here is the result, in this case the list of elements created by adding a new sheet to the project:

C:\tmp\ >diff RevitElementsBeforeSheet.txt RevitElementsAfterSheet.txt
2581a2582,2595
> Id=137766; Class=ViewSheet; Category=Sheets; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a26
> Id=137767; Class=Element; Category=?; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a27
> Id=137768; Class=Element; Category=Viewports; Name=Title w Line; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a28
> Id=137769; Class=Element; Category=?; Name=A101 - Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a29
> Id=137770; Class=Element; Category=Work Plane Grid; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2a
> Id=137771; Class=SketchPlane; Category=?; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2b
> Id=137772; Class=FamilyInstance; Category=Title Blocks; Name=A0 metric; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2c
> Id=137773; Class=View; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2d
> Id=137774; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2e
> Id=137775; Class=Element; Category=Viewports; Name=Title w Line; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2f
> Id=137776; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a30
> Id=137777; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a31
> Id=137778; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a32
> Id=137779; Class=Element; Category=Schedule Graphics; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a33

If these lines are truncated in the browser view, you can copy and paste them to an editor to see the full text.

From this you can see that the new sheet has the element id 137766, and the associated title block is a FamilyInstance with id 137772.

Once the new elements have been identified, the Revit API introduction labs built-in parameter checker can be used to explore their data. In the Revit user interface, I can select the sheet via Modify > Element ID > Select by ID > 137766 > OK and then invoke the built-in parameter checker to explore its parameters.

Looking at the sheet parameters sorted by type and going through all parameters whose value is an element id, I see that there is no reference to 137772, so the sheet does not have a parameter explicitly specifying the title block by its element id, as one might have hoped.

Looking at the title block parameters yields better results, among others the family that you are asking for and the sheet number:

ELEM_FAMILY_AND_TYPE_PARAM  
  Family and Type  
  ElementId 28295   
  Title Blocks 'A0 metric'

SHEET_NUMBER                
  Sheet Number     
  String            
  A101

This means that although we have not found a pointer from the sheet to the title block, we have found information about the inverse relationship from the title block to the sheet. We can therefore use the relationship inverter algorithm to identify the title block from the sheet, if needed.

I also had an idea for another, completely different approach: I tried deleting the sheet again after it had been added and checked the resulting list of elements after that operation:

C:\tmp\ >diff 
  RevitElementsAfterSheetDelete.txt 
  RevitElementsBeforeSheet.txt

Files are identical.

Happily, as it turns out, the new list of elements is exactly the same as it was before the sheet was added. This means that the deletion of the sheet caused the associated title block to be deleted as well. This means that we can probably make use of the doc.Delete method to detect dependent elements. Using that approach, you delete the sheet inside a transaction, save the list of element ids returned by the doc.Delete method, and abort the transaction to undo the deletion operation. The list of ids will then include element ids of both the sheet and the associated title block.

I hope this resolves your issue twice over.

Title Block Modification

By the way, Ricardo Cardial raised a related question on how to modify the text labels defined in the title block, which we will partially repeat here in order to ensure that these useful ideas do not get lost:

Question: How can we change the information of the scale label shown in title blocks? When we have two different scales on the sheet, the value is 'As indicated'. I would like to change that, for instance to translate it to French or Italian.

Answer: Look at the original comment for the full answer, which consists of two parts. They can be summarised like this:

• Read the data through the built-in parameter SHEET_SCALE with the display name 'Scale'. It is a string-valued parameter and is unfortunately marked as read-only.
• Modify the family file used to define the title block of the sheet.

Analytical Support Tolerance

Here is an interesting issue dealing with the analytical model in Revit Structure. As we see below, the issue is not really API related, but since one symptom is the missing data obtainable through the API, it is worth an explanation.

Question: We have created two columns over a three-pile cap foundation and are trying to retrieve the support data from their analytical models:

Unfortunately, the support data of the column is available only if its centre line is exactly over the analytical model location of the pile cap foundation. Else, it is not available and the property simply returns null. The main purpose of this requirement is actually to find the link between the column and the pile cap. How can we achieve this, please?

Answer: Happily, this situation is easily resolved by modifying the analytical support tolerance. First, note that the missing support data is not an API-specific problem. If you select the column through the user interface, the Show Related Warnings button is active and the warning says that the column may not be supported.

The pile cap foundation is actually four foundations – one cap foundation and three pile foundations. Geometry for the cap foundation starts at Level 1 and goes down 900. The geometries for the three pile foundations start at -900 and go down 6900. In Revit, the default position for the Isolated Foundation analytical model is at the top of the geometry. Since this is at -900, the analytical models for the pile foundations are at that elevation.

Analytical Support is governed by the Analytical Support tolerance, shown on the Analytical Model Settings tab of the Structural Settings dialog. In the attached file, this tolerance is set at 300. So even when the column's analytical model is directly over the pile foundation's analytical model, the thickness of the cap foundation (900) is keeping the column from seeing the pile foundation's analytical model.

To overcome this obstacle, increase the tolerance from 300 to 900. Then when you move the column over the top of the pile foundation, it will see the pile foundation, and the column will consider the pile foundation as a valid support.

Although that resolves the current problem, here are two additional general hints for approaches to find the link between two elements located close to each other:

• FindReferencesByDirection.
• Geometric analysis.

The FindReferencesByDirection method to find the link between the two elements determines that the pile cap foundation is located directly underneath the second column and hence is supporting it. This can be achieved by shooting a ray straight down from a point slightly raised up from the lower endpoint of the column and using FindReferencesByDirection to discover the foundation element directly underneath. FindReferencesByDirection returns an array of elements, faces, and references found when moving through the model from a specified point in a specified direction. Its use is demonstrated by the RayTraceBounce SDK sample.

You can also determine their relationship by pure geometric analysis, e.g. using a filter to collect all the structural elements on the relevant levels and then comparing the locations of their solids' faces with each other. The AreSolidsCut method defined by the RoomsRoofs SDK sample may be helpful in this context. Geometric analysis may or may not be simpler than using FindReferencesByDirection.

Door Marks

Here is a question from Håvard Dagsvik of Cad Quality as on door marks. It can obviously be generalised to other model marks in the BIM as well.

Question: One of the best documentation features of Revit is the function assigning numeric values to the Mark parameters. If you insert 5 doors they are marked 1-5. Now if door 3 and 5 are deleted, then a new door will still start its mark on 6. Even if the project is closed and reopened, the next door still gets Mark# 6. That means there has to be a list inside Revit somewhere of the mark numbers that previously has been used, and Revit avoids reusing those numbers again. Is there a way through the API to get to that list? And somehow manipulate it to make Revit start counting on our choice of number?

Answer: Using the RvtMgdDbg BIM debugging and analysis tool or the Revit API introduction labs built-in parameter checker to explore various element parameters, I see that the Mark parameter is accessible through the built-in parameters ALL_MODEL_MARK. This is a read-write parameter:

ALL_MODEL_MARK  Mark  String/Text  read-write  4

You can therefore obtain a list of all door marks by filtering for all door instances and reading their ALL_MODEL_MARK parameter value.

I do not believe that you can manipulate Revit to influence the automatic mark counting setting used by the automatic assignment, but what you certainly can do is implement an external command which renumbers existing door instances by changing the value of their ALL_MODEL_MARK parameter value in any way you please.

To demonstrate reading and listing all existing door marks as well as modifying the marks of existing doors, I created a new Building Coder sample command CmdListMarks, which implements the following functionality:

• Select all door instances in the model.
• Iterate over the selected door instances.
• Create a dictionary whose keys are all door marks in the model and mapping each mark to a list of all doors with that mark.
• Print out the sorted dictionary contents.
• If any door elements have been selected prior to running the command, modify their door marks to a predefined hardcoded value "42".

Here is the output produced by running this command in a small model with four doors with the marks 1, 2 and 4, where 4 is duplicated on two doors.

4 doors found.
3 door marks found:
  1: 1 door
  2: 1 door
  4: 2 doors

If I select the two doors marked 4 and run the command again, their marks are modified to 42. Running it yet again lists the new mark settings:

4 doors found.
3 door marks found:
  1: 1 door
  2: 1 door
  42: 2 doors

Here is the complete code of the new external command:

static bool _modify_existing_marks = true;
const string _the_answer = "42";
 
public CmdResult Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  Autodesk.Revit.Creation.Filter cf
    = app.Create.Filter;
 
  List<Element> doors
    = new List<Element>();
 
  Filter f1 = cf.NewTypeFilter(
    typeof( FamilyInstance ) );
 
  Filter f2 = cf.NewCategoryFilter(
    BuiltInCategory.OST_Doors );
 
  Filter f = cf.NewLogicAndFilter( f1, f2 );
 
  int n = doc.get_Elements( f, doors );
 
  Debug.Print( "{0} door{1} found.",
    n, Util.PluralSuffix( n ) );
 
  if( 0 < n )
  {
    Dictionary<string, List<Element>> marks
      = new Dictionary<string, List<Element>>();
 
    foreach( FamilyInstance door in doors )
    {
      string mark = door.get_Parameter(
        BuiltInParameter.ALL_MODEL_MARK )
        .AsString();
 
      if( !marks.ContainsKey( mark ) )
      {
        marks.Add( mark, new List<Element>() );
      }
      marks[mark].Add( door );
    }
 
    List<string> keys = new List<string>(
      marks.Keys );
 
    keys.Sort();
 
    n = keys.Count;
 
    Debug.Print( "{0} door mark{1} found{2}",
      n, Util.PluralSuffix( n ),
      Util.DotOrColon( n ) );
 
    foreach( string mark in keys )
    {
      n = marks[mark].Count;
 
      Debug.Print( "  {0}: {1} door{2}",
        mark, n, Util.PluralSuffix( n ) );
    }
  }
 
  n = 0; // count how many elements are modified
 
  if( _modify_existing_marks )
  {
    ElementSet els = doc.Selection.Elements;
 
    foreach( Element e in els )
    {
      if( e is FamilyInstance
        && null != e.Category
        && (int) BuiltInCategory.OST_Doors
          == e.Category.Id.Value )
      {
        e.get_Parameter(
          BuiltInParameter.ALL_MODEL_MARK )
          .Set( _the_answer );
 
        ++n;
      }
    }
  }
 
  // return Succeeded only if we wish to commit 
  // the transaction to modify the database:
 
  return 0 < n
    ? CmdResult.Succeeded
    : CmdResult.Failed;
}

The command returns Succeeded only if the BIM has actually been modified, otherwise Failed. This ensures that the document dirty flag stored in its IsModified property is not set unnecessarily.

Here is version 1.1.0.47 of the complete Building Coder sample source code and Visual Studio solution including the new command.

The Revit MEP API

By the time you read this, I will be away happily on a one-week vacation in Italy. I hope you and the blog manage yourselves and behave well until I return. I scheduled some items to be published in my absence, though.

In previous posts, we already had a look at the new MEP-specific API features in Revit 2010 and the classes involved in defining and representing MEP connectors in particular. On August 27^th 2009, we held the first webcast dedicated entirely to Revit MEP programming. This post provides an abbreviated overview of the complete Revit MEP and the webcast contents with links to available related materials, including the following topics:

• The Revit MEP API
• MEP model analysis
• Hierarchical systems and connectors
• Electrical systems
• HVAC and plumbing systems
• Sample applications
• Materials and further reading

The Revit MEP API

Revit MEP is a flavour of Revit for work in the mechanical, electrical and plumbing domains. HVAC, i.e. heating, ventilation and air conditioning, is considered part of the mechanical domain. Efficient work in these areas requires strong model analysis tools in addition to read and write access to the components and data used to model the electrical, HVAC and piping systems in Revit MEP. Some of the required MEP specific functionality includes access to the MEP project information, Green Building XML, spaces and zones, the electrical, duct and pipe systems, their components, properties and parameters, methods for element creation and modification, and system traversal and analysis.

Most of the Revit API is generic and applies to all three flavours of the Revit product, i.e. Architecture, MEP and Structure. All three flavours of Revit also include the same .NET assembly named RevitAPI.dll providing API access to third-party applications. However, some specific additional features exist for each of the flavours as well, for instance some room-related functionality in Revit Architecture and access to the analytical and MEP models in Revit Structure and MEP respectively. If API functionality not supported by the currently running flavour is accessed, the call will simply do nothing or return null.

In Revit 2008, no MEP-specific functionality was provided by the API. It was still possible to analyse and manipulate an HVAC system using the generic Revit API methods, for instance by accessing ducts as generic Revit elements and reading and writing their properties using the generic parameter access. We used this to create a sample application for HVAC air terminal analysis and sizing, presented at Autodesk University 2007. Revit 2009 introduced the first MEP-specific API support, including classes for electrical and mechanical equipment, lighting device and fixture, connector, electrical system, space and zone, the MEP model property on family instances, and the ability to create and modify MEP elements. In Revit 2010, the MEP-specific API was a focal point of the API development and greatly enhanced, especially the support for HVAC and piping systems.

MEP Model Analysis

Access to the MEP Project Info is provided through the gbXMLParamElem element and its properties, which is accessed through the ProjectInfo.gbXMLSettings property. The available data includes PostalCode, ProjectLocation, BuildingService, BuildingConstruction, GroundPlane, ShadingSurfaces, and ProjectPhase.

Green Building XML or gbXML export is initiated by a call to the Document.Export method:

Document.Export( string folder, string name, GBXMLExportOptions );

Using spaces instead of rooms, and zones to group spaces, enables a subdivision of the architectural rooms into subspaces required for MEP analysis. The AddSpaceAndZone SDK sample demonstrates the programmatic creation and management of spaces and zones. The FamilyInstance class already had a Room property to determine in which room an instance is located, and now an analogous Space property has been added for MEP usage.

Several model inspection utility methods added in Revit 2010 are especially useful in the MEP domain. One group helps determine the relationships between and contents of volumes, rooms and spaces:

• Room.IsPointInRoom determines if a 3D point is in the volume of a room.
• Space.IsPointInSpace determines if a 3D point is in the volume of a space.
• GetRoomAtPoint and GetSpaceAtPoint return the room or space containing a given 3D point.

The new ray intersection method can be used to determine proximity of elements:

• FindReferencesByDirection returns an array of elements, faces, and references found when moving through the model from a specified point in a specified direction.

One use of FindReferencesByDirection is demonstrated by the RayTraceBounce SDK sample.

Hierarchical Systems and Connectors

Many of the building blocks of an MEP system are represented in Revit by family instances. The generic family instance definition in the Revit API has been enhanced to provide access to additional MEP-specific properties and data, and provide classes to represent systems and connections between system components.

The objects dealt with in the MEP domain are organised into hierarchical structures. The top level node in these structures is an MEP system, represented by the MEPSystem class. This is the base class for the derived classes ElectricalSystem, MechanicalSystem and PipingSystem. The system has properties to access the base equipment or panel, the terminal elements, and the connector manager. The derived classes have many additional domain specific properties.

The Revit 2009 API introduced the MEPModel and Connector classes as fundamentals for programmatically representing and accessing the MEP model. It is accessed through the FamilyInstance.MEPModel property, and one of its main purposes is to provide access to the connector manager.

We have logical and physical connections between MEP components. Logical connections are used in the electrical domain, where wires and cables are not necessarily modelled individually. Physical connections are used in the mechanical and plumbing domains, where the connectors define and transmit sizing and flow information from one part to the next.

A connector is part of an MEP element such as a duct, pipe, fitting, or piece of equipment. The Connector class is used to represent connectors in the project environment. Individual stand-alone connector elements need to be created inside a family to define the component and are represented there by the DuctConnector, PipeConnector and ElectricalConnector classes.

The connector defines geometry, e.g. its oval, round or rectangular shape, and dimensions such as width, height and radius. It also maintains a coordinate system and system data such as domain, system type, flow, direction.

Electrical Systems

Electrical systems are organised hierarchically in Revit MEP. The root elements are panels. Each panel is connected to a number of systems, also known as circuits. Each system or circuit consists of a number of circuit elements, some of which may be further panels, and so on, recursively. Cables and wires need not be modelled individually, and the connections between the electrical system components are defined by logical connectors rather than physical ones. The Revit 2009 API introduced the classes ElectricalEquipment, LightingDevice, LightingFixture, ElectricalSystem, specialisations of the base MEPModel and MEPSystem classes, to represent electrical components and systems. These elements all have a connector manager, whose Connectors property returns logical as well as physical type connectors:

ElectricalSystem sys;
ConnectorSet connectors = sys.ConnectorManager.Connectors;

This makes it very simple to analyse and traverse the electrical system hierarchies similarly to the approach demonstrated by the TraverseSystem SDK sample for duct and piping ones.

HVAC and Plumbing Systems

New support for HVAC and plumbing was provided with Revit 2010, which introduced the Autodesk.Revit.MEP namespace containing a wealth of new classes and functionality, as well as moving existing MEP-related classes to the MEP namespace. The main components in HVAC and piping hierarchy are the top level systems, ducts, pipes, fittings and connectors:

• Systems to manage the top level system properties.
• Ducts and pipes to define the main flow elements.
• Fittings to implement bends and branches in the system.
• Connectors to hook up the ducts, pipes and fittings.

The classes MechanicalSystem and PipingSystem introduced in Revit 2010 provide the following top-level system functionality:

• Access to equipment, connectors and system type.
• Access to system properties such as flow and static pressure.
• Analysis of system contents through the DuctNetwork or PipeNetwork property.

The elements contained within a system are not automatically returned in the flow direction. The TraverseSystem SDK sample demonstrates how to query the connector managers to implement traversal in direction of flow for a given system.

Ducts and pipes are represented by the classes Duct, FlexDuct, Pipe and FlexPipe, derived from the MEP curve type. They provide the following functionality:

• Read access to duct properties, types, and geometry.
• Change duct or pipe type.
• Move or layout duct or pipe.

The layout functionality can be driven by two points, one point and a connector, or two connectors.

Fittings are represented by family instances, which are created with dedicated methods on the Autodesk.Revit.Creation.Document class for inserting Elbow, Tee, Cross, Takeoff, Transition, and Union elements. The fitting properties, shape and dimensions can be accessed through the FamilyInstance.MEPModel property.

Connectors limited to the electrical realm were introduced in Revit 2009. In Revit 2010, we have connectors for the mechanical and piping domains as well. The connector is an item that is a part of another element such as a duct, pipe, fitting, or equipment. The basic features of connectors and the different classed used to represent them in the family and project contexts were mentioned above. The additional HVAC-specific connector features include properties to read the flow, coefficient and demand. They also provide access to physical properties like Origin, Angle, Height, Width and Radius.

We have read and write access to so-called assigned connector properties. These are connector properties that can be overridden by the user and are dependent on the overall network condition, including characteristics like Flow, Flow Config, Coefficient, Loss etc. These depend on the system being well connected, the configuration of the family within the system, and how the family is constructed.

Connector size and location can be modified. Connectors can be disconnected to insert a new fitting into a network or connect two ducts into a transition.

• The family connector elements define Flow, Flow Configuration, Coefficients, and Loss Method.
• Read duct, pipe, and fitting connector properties such as Flow, Coefficient, and Demand.
• Access physical connector properties e.g. Origin, Angle, Height, Width, Radius.
• Change connector size and location.
• Connect and disconnect.

The creation document provides a number of methods for the creation of HVAC and plumbing elements within the project environment, including new mechanical or piping systems, new duct and pipe elements, and new fittings. In the context of a family, the different types of duct, pipe and electrical connectors are represented by specific elements that can be created by the FamilyItemFactory class, accessed through the Document.FamilyCreate property.

Sample Applications

The MEP-specific sample applications include both those provided in the standard Revit SDK as well as a non-SDK one created for this presentation on the RME API.

The introduction of an MEP specific API with Revit 2009 was accompanied by two SDK samples:

• AddSpaceAndZone demonstrates handling the new space and zone elements.
• PowerCircuit demonstrates manipulation of electrical power circuits.

The Revit 2010 SDK includes the following new MEP-specific SDK sample applications:

• AutoRoute: Route a set of ducts and fittings between a source, the air supply equipment, and the sink, two air outlet terminals.
• AvoidObstruction: Detect and resolve obstructions between ducts, pipes, and beams.
• TraverseSystem: Traverse a well-connected mechanical or piping system in the direction of flow.
• CreateAirHandler: Create an air handler and add connectors.

The first three demonstrate RME API features in the project context, the fourth uses the family API.

Finally, we provide a non-SDK sample application named ‘mep’. It implements some HVAC oriented commands making use of the generic Revit API to analyse and manipulate duct elements for automatic air terminal sizing, and others which implement an electrical sample for analysis and display of an electrical system in a tree view reproducing the Revit system browser structure or showing the full connection hierarchy tree:

• HVAC air terminal analysis and sizing.
• Electrical system connectivity analysis and hierarchical display.

Materials and Further Reading

A more extensive document discussing the Revit MEP API and the related samples in deeper detail as well as other useful material is provided with the recording of Revit MEP Programming Webcast held on August 27th 2009, available through the ADN or Autodesk Developer Network API training schedule (also accessible via www.autodesk.com/apitraining), filter for 'Revit MEP API', and click on the download link. This material is accessible to all developers, regardless of ADN membership.

Remove all Geometry from a Family

Here is a question from Joel Karr of Environmental Systems Design, Inc that nicely complements the issue of identifying model elements in a project file with the subsequent correction added.

Question: Is it possible to delete all geometry from a Revit RFA family file? I would like to keep all parameters but delete all geometry.

Answer: To achieve what you desire, we first need to identify all elements contributing geometry to the model, similarly to the model element selection issues mentioned above.

This is simpler in a family file than in a project file, since there are normally less elements and almost all elements having geometry are the ones we are interested in.

I implemented a sample application RemoveRfaGeom to test this, with the following mainline code for its Execute method:

public IExternalCommand.Result Execute( 
  ExternalCommandData commandData, 
  ref string message, 
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  ElementIterator it = doc.Elements;
  Options opt = app.Create.NewGeometryOptions();
  List<Element> a = new List<Element>();
 
  while( it.MoveNext() )
  {
    Element e = it.Current as Element;
 
    if( null != e.get_Geometry( opt ) )
    {
      a.Add( e );
    }
  }
 
  int n = a.Count;
  Debug.Print( 
    "{0} element{1} have non-null geometry{2}", 
    n, 
    ( 1 == n ? "" : "s" ),
    ( 0 == n ? "." : ":" ) );
 
  ElementSet els = new ElementSet();
 
  foreach( Element e in a )
  {
    string cat = (null == e.Category)
      ? "<null>"
      : e.Category.Name;
 
    Debug.Print(
      "Category={0}; Name={1}; Id={2}; Type={3}",
      cat,
      e.Name,
      e.Id.Value.ToString(),
      e.GetType().Name );
 
    if( null == e.Category )
    {
      els.Insert( e );
    }
  }
 
  ElementIdSet ids = doc.Delete( els );
 
  n = (null == ids) ? 0 : ids.Size;
 
  Debug.Print( "{0} element{1} deleted.",
    n,
    ( 1 == n ? "" : "s" ) );
 
  return IExternalCommand.Result.Succeeded;
}

It performs the following steps, assuming that the active document is indeed a family document:

• Iterate over all family document elements.
• Identify and list all elements with non-null geometry.
• Create a set of all elements with geometry whose category is null.
• Delete the latter set and display the number of deleted elements.

Running this in the metric library rectangular column family file 'M_Rectangular Column.rfa' produces the following output:

2 elements have non-null geometry:
Category=; Name=Extrusion; Id=105; Type=Extrusion
Category=Cameras; Name=View 1; Id=427; Type=Element
13 elements deleted.

As you can see from this, there are some elements having geometry that you presumably do not want to eliminate, such as the camera, so you will need to remove those from the set before deletion. In this case, I simply noted that the camera has a non-null category, whereas the category of the extrusion I want to remove is null, so I just check the null category property to select the extrusion.

Secondly, deleting an element causes other dependent elements to be deleted also, so even though we just pass in one single extrusion element to the Delete method, a whole group of other elements are eliminated as well. We already discussed and made use of this effect to determine the association between a tag and the tagged element and between a host and its hosted elements.

Here is the complete Visual Studio solution RemoveRfaGeom implementing the new command.

Integration with a Database or ERP System

A while ago, I published Miroslav Schonauer's popular high-level overview of Revit and database integration. Here is an additional useful note from Anthony Hauck on this topic:

Question: How can I integrate Revit with an ERP solution or an SQL database?

Answer: Revit information can be exported to an ODBC-compatible database. ODBC export is a native feature of Revit. The Labs posting RDBLink demonstrates a similar capability using the API, with the additional feature of being able to change some parameters within a Revit model by editing the resulting database and re-importing the changes. Some of these parameter changes can affect Revit model geometry.

The availability of RDBLink has already been mentioned briefly previously.

Retrieving Newly Created Elements

The day before yesterday, I demonstrated the use of the Mirror method. Henrik Bengtsson of Lindab immediately came back with a question on this. Funnily enough, the reason I quickly posted the article the day before yesterday was because someone completely different asked the exact same two questions as Henrik in the exact same sequence. There seems to be some kind of morphogenetic resonance going on among Revit developers. Anyway, here is Henrik's question:

Question: The mirror command works all right according to the description. I now face another issue that I had not thought of before. How can I get a reference to the newly created mirrored objects? Those are actually the objects that I want to continue working with.

Answer: Because this question was already asked once this morning, I had some time to meditate deeply on how to retrieve the newly created elements generated by the mirroring operation. My first idea was to grab them by parsing the tail of the journal file, but unfortunately they are not listed there. My second idea works, however:

• Ask the document for all its elements before the mirroring operation and remember the total number n.
• Call the Mirror method, generating a number of new elements.
• Ask the document for all its elements again, and retrieve the ones whose index exceeds n.

I make use of two helper methods for this:

• GetElementCount determines the total number of document elements before the mirroring operation.
• GetElementsAfter returns a list of all document elements whose index exceeds a given number.

Here is the implementation of these two methods:

int GetElementCount( Document doc )
{
  int count = 0;
  ElementIterator it = doc.Elements;
  while( it.MoveNext() ) 
  { 
    ++count; 
  }
  return count;
}
 
List<Element> GetElementsAfter( int n, Document doc )
{
  List<Element> a = new List<Element>( n );
  ElementIterator it = doc.Elements;
  int i = 0;
 
  while( it.MoveNext() ) 
  {
    ++i;
 
    if( n < i )
    {
      a.Add( it.Current as Element );
    }
  }
  return a;
}

Here is the code for the new external command implementing this. It is a simple extension of the mirroring command CmdMirror presented on Wednesday:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
 
ElementSet els = doc.Selection.Elements;
 
Line line = app.Create.NewLine( 
  XYZ.Zero, XYZ.BasisX, true );
 
int n = GetElementCount( doc );
 
doc.Mirror( els, line );
 
List<Element> a = GetElementsAfter( n, doc );
 
string s = "The following elements were mirrored:\r\n";
 
foreach( Element e in a )
{
  s += string.Format( "\r\n  {0}",
    Util.ElementDescription( e ) );
}
Util.InfoMsg( s );
 
return CmdResult.Succeeded;

Here is version 1.1.0.41 of the complete Visual Studio solution including the mirroring command CmdMirror and the new command CmdMirrorListAdded.

Disclaimer: Please note that there is nothing in the Revit API documentation stating that the iterator returned by doc.Elements will traverse the elements in the order they were added to the database. That happens to be the case today and has been so in the past. This behaviour may change without notice in the future.