The Building Coder

AU Virtual free for ADN Members

Kean Walmsley just announced that a free Premier Pass to Autodesk University virtual is available for members of the Autodesk Developer Network.

Please join us there. We are presenting at both AUv and the non-virtual AU:

• Kean's F# sessions.
• AutoCAD-related AU and AUv sessions.
• The Revit Family and MEP APIs.

I am looking forward to seeing or hearing from you in the next couple of days!

Revit API Flavours

Maher raised an interesting question regarding the different flavours of the Revit API:

Question: I have a few questions on Revit MEP, Arch, and Structure in general. What are the major highlights of each API? I downloaded the SDK and tried to read through. But could not get my head around it as it is very overwhelming. It would be great if you could post something in the difference between these three flavours both in terms of API and in general use. They seem to do the same thing in many cases. I am confused.

Answer: By far the major part of the Revit API is identical for the three flavours, and to get started with it you need not worry about the differences. All the basic functionality and most objects that I have ever had occasion to use are provided in all three flavours.

If you try to access a property that is not available in the particular flavour of Revit that your application is running in, the property will generally simply return a null value or sometimes throw an exception, as Shifali is currently painfully discovering, being unable to access the gbXML settings in Revit Architecture.

You can check what flavour you are running in by querying the application object as demonstrated by the Revit API introduction labs sample command Lab1_2_CommandArguments:

  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
  View view = commandData.View;
  string s = "Application = " + app.VersionName;
  s += "\r\nVersion = " + app.VersionNumber;
  s += "\r\nDocument path = " + doc.PathName;
  s += "\r\nDocument title = " + doc.Title;
  s += "\r\nView name = " + view.Name;
  LabUtils.InfoMsg( s );

In the Revit 2010 API, new LanguageType and ProductType enumerations and corresponding properties on the application object were introduced to enable an add-in to query and analyse the underlying product and user interface language without resorting to any string comparisons:

  LanguageType lt = app.Language;
  ProductType pt = app.Product;

We have previously taken a deeper look at the Revit Structure and MEP APIs and mentioned some of the specific features of each.

The easiest way that I can think of to see the exact differences between the three flavours of the Revit API is to look at the class diagram in the Revit SDK provided in "Revit API Class Diagram.png". It shows all of the namespaces and classes defined in the Revit API and colour codes them into various groups, including separate groups for the three product flavours.

The developer guide in the document "Revit 2010 API Developer Guide.pdf" also includes the three separate chapters dealing with the API specifics of each flavour:

23. Revit Architecture
    23.1   Rooms
    23.2   Energy Data
24. Revit Structure
    24.1   Structural Model Elements
    24.2   AnalyticalModel
    24.3   Loads
    24.4   Analysis Link
25. Revit MEP
    25.1   MEP Element Creation
    25.2   Connectors
    25.3   Family Creation

AU 2009

These days I am pretty occupied with the preparation of my sessions for Autodesk University 2009:

• CP308-2 All Systems Go in the New Autodesk Revit MEP API
• CP9118-1 The New Autodesk Revit Family API: Everything is Relative

The Family API one is a virtual class which requires special preparation, since it is being recorded and broadcast worldwide for Virtual Autodesk University. As Rick Graham pointed out, virtual AU was created for those who are not able to make it to Las Vegas in person, and is free for subscription customers.

Here are links to the standard class catalogue and the virtual classes.

I would love to see you in person in the classroom session, or chat with you live during one of the virtual ones.

System Versus User Family Category

Here is a simple question and suggestion on classifying categories into built-in system versus user defined.

Question: Given an arbitrary element, how can I determine whether it belongs to a system family as opposed to a user-defined family? I thought I might look at its category, but how can I see whether that is system-defined? For example, I see that a duct has a category id of -2008000. Can I depend on the fact that this category id value is negative? Or is there any other way to determine this?

Answer: There is currently no API method to distinguish system categories from user defined ones short of creating your own hardcoded list. All built-in categories have negative values, but this includes system family types, family types, and subcategories of each, so that will not help you resolve this issue.

How could such a list be created?

Unfortunately, that would have to be done manually. This Family Category and Parameters dialogue lists all the family based categories:

If the category is a top level category and not in this list, then it is probably a system family category.

Modeless Pressure Drop Tool

This weekend I went with a couple of men friends to spend two days together in Arcegno near Locarno. One afternoon we went climbing together in Ponte Brolla at the end of the Maggia Valley. We did some very easy climbs, because some of us were absolute beginners, Jimmy (4b), Ostro (5a), Mekka (4c), and Muckel (5b), wonderful slab climbing on the big, clean, warm sloping rock face. The next day we went on a hike from Aurigeno, a few kilometres up the Maggia Valley, up to Capoli (1001 m), Prada, and Chegg, to beautiful old stone houses on a mountain path with no connection to any road and even a group of tipis and a view out over the Lago Maggiore. Just before boarding the train back into the colder and moister north, I took a very nice long walk along the bank of the lake from Locarno out toward Tenero in order to savour the beautiful clear and sunny Sunday afternoon.

Back home again I return to the Revit API and BIM analysis. One simple BIM exploration required in the MEP HVAC domain is analysis of the pressure drop caused in a ventilation system by the various duct and fitting elements.

What would the ideal user interface for such an analysis tool look like?

One very minimalistic approach would be to hover over or pick the duct or fitting element of interest and see the result immediately displayed, wouldn't it?

This minimalistic interface can actually easily be implemented using the current Revit API, as we demonstrated in our discussion on modeless dialogues. A modeless dialogue is especially useful for interactive exploration of the Revit model, since the dialogue box and the Revit user interface both remain active at the same time.

Joel Karr of CADworks created a very sweet little implementation of just this kind of modeless pressure drop tool with a number of interesting aspects, such as:

• The command loop managing user interaction to select elements and control the modeless dialogue.
• Functionality to determine the pressure drop data from a given Revit element.
• Displaying the data to the user, which can be achieved very simply using an appropriate data container.

Joel shows us how to harness some powerful .NET framework functionality to implement the complete tool with a minimum of coding.

The tool is launched by invoking an external command. This displays a modeless dialogue which initially has no data to display:

As long as it is running, it prompts the user to select a duct or fitting element. Every time an element is selected, the dialogue updates to reflect the pressure drop in the selected element:

As soon as the form is closed, the command terminates.

You will probably be surprised to see how little code is required to achieve this. It takes much more text to describe it thoroughly in words, though:

• Data container.
• Modeless form.
• Determining the pressure drop.
• Command loop.
• Retrieve Revit window handle.
• Retrieve pressure drop from selected element.
• Displaying the data in the form.
• Caveat.
• Source code.

Let's start by looking at Joel's minimalistic data container class:

Data Container

Here is a note from Joel on implementing his modeless pressure drop tool based on the original modeless dialogue sample:

I changed up your modeless dialogue a little bit to store the selection in a data class. That way when I dispose the form I can dispose the selection and change the using Boolean to false. Then it can exit the while loop of the form.

The data container makes use of the auto-implemented properties which enables a very succinct implementation:

public class Data
{
  public bool UsingWindow { get; set; }
  public bool GetElements { get; set; }
  public double PressureDrop { get; set; }
  public Selection Selection { get; set; }
  public Data()
  {
    UsingWindow = true;
    GetElements = true;
  }
}

The two Boolean member variables are used to control the flow in the main command loop. The other two store the current interactive user selection in Revit and the pressure drop calculated for the currently selected element. It can't get much shorter than that, can it?

Modeless dialogue form

The modeless dialogue used to display the data basically just defines the label to receive the pressure drop value. The only code that needs to be added to the automatically generated Visual Studio designer code is the data container instance member and its initialisation:

public partial class WindowHandleForm : Form
{
  public Data CDWKSData { get; set; }
 
  public WindowHandleForm(Data data)
  {
    InitializeComponent();
 
    CDWKSData = data;
  }
}

We will see below how the pressure drop value is retrieved from the Revit database and sent to the label in the form.

Determining the Pressure Drop

Now we come to the central question of querying the Revit element for its pressure drop.

Question: I would like to be able to see the result of Revit's Pressure Drop Calculations for duct fittings. I can choose the ASHRAE Table and the Loss Method but would like to see the result as the Pressure Drop parameter similar to the straight ducts. Is there a way to use the Pressure Drop Calculator through the API? Or is there a way to make this show? Here is the area I would like to see populated:

On a duct elbow, I looked at the value of the built-in parameter RBS_PressureDrop, but it is null when it is not filled out through the user interface. The value is not filled in automatically when I view the duct fitting through Revit. I need a method that actually calculates the pressure drop for a fitting. To do this by hand, an engineer can look at the size of the fitting, select the correct ASHRAE table, and then look up the value. Revit does this automatically but does not display the result.

Answer: This data is available from the connectors, not the fitting itself. You can use the Connector.PressureDrop property, which returns the instantaneous pressure drop of a given connector, calculated according to system. This means that to determine the pressure drop of fitting, such as a duct elbow, you need to iterate over its connectors and retrieve the data from them. The pressure drop of the elbow maps to the one of the connectors on this family instance. The Connector.PressureDrop property will not return a null value. Here is a pseudo-code snippet:

double get_pressure_drop( 
  FamilyInstance ductElbow )
{
  foreach( Connector c in 
    ductElbow.MEPmodel.ConnectorManager.ConnectorSet )
  {
    if( this connector c is the one required )
    {
      break;
    }
  }
  return c.PressureDrop;
}

Command Loop

Now we need to tie together the code accessing the pressure drop data to populate and drive the modeless form. How does this all fit together to provide the useful functionality presented above?

Here is the entire definition of the external command class with the mainline code of its Execute method, including three collapsed code regions which we expand and explore in more detail below:

public class Command : IExternalCommand
{
  static WindowHandle _hWndRevit = null;
 
  public CmdResult Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements)
  {
    #region Get Revit Window Handle
 
    Autodesk.Revit.Application app 
      = commandData.Application;
 
    Document doc = app.ActiveDocument;
 
    Data data = new Data();
    data.Selection = doc.Selection;
 
    using( WindowHandleForm f 
      = new WindowHandleForm( data ) )
    {
      f.Show( _hWndRevit );
 
      while( data.UsingWindow )
      {
        if( data.GetElements )
        {
          // Clear Selection and Pressure Drop Value:
 
          data.Selection.Elements.Clear();
          data.PressureDrop = 0;
 
          // User Selects an Element:
 
          data.Selection.StatusbarTip 
            = "Please select a duct fitting.";
 
          data.Selection.PickOne();
 
          SelElementSet ss = data.Selection.Elements;
 
          #region Process Selection for Pressure Drop

          #region Send Information to Window Label

        }
      }
    }
    return CmdResult.Succeeded;
  }
}

Note how the Boolean UsingWindow and GetElements member variables of the data container class are used to control the flow and termination of the loop.

Retrieving the Revit Window Handle

The window handle is retrieved and stored in a WindowHandle helper class using the same code as in the initial discussion of the modeless dialogue:

#region Get Revit Window Handle
if (null == _hWndRevit)
{
  Process process
    = Process.GetCurrentProcess();
 
  IntPtr h = process.MainWindowHandle;
 
  _hWndRevit = new WindowHandle(h);
}
#endregion // Get Revit Window Handle

Retrieving the Pressure Drop from a Selected Element

Here is the final resulting code to retrieve the pressure drop data from any applicable selected element, be it a duct or a fitting:

#region Process Selection for Pressure Drop

foreach (Element e in ss)
{
  if (e is Duct)
  {
    Duct duct = e as Duct;
 
    Parameter p
      = duct.ParametersMap.get_Item( 
        "Pressure Drop" );
 
    data.PressureDrop = p.AsDouble();
  }
  else if (e is FamilyInstance
    //&& e.Category.Name == "Duct Fittings"
    && e.Category.Id.Value.Equals( 
      (int) BuiltInCategory.OST_DuctFitting ) )
  {
    FamilyInstance fitting = e as FamilyInstance;
 
    foreach (Connector c in 
      fitting.MEPModel.ConnectorManager.Connectors)
    {
      if (c.PressureDrop > data.PressureDrop)
      {
        data.PressureDrop = c.PressureDrop;
      }
    }
  }
}
#endregion

Identifying a duct element is easy, since the Revit API defines a dedicated class for it. In that case, the pressure drop is available directly from the corresponding "Pressure Drop" element parameter.

On the other hand, a fitting is a family instance with a 'Duct Fittings' category, which we obviously identify using the language independent built-in category comparison. If the selection is a fitting we need to loop through its connectors and retrieve the highest pressure drop value from those instead. Multiple branch fittings would need to return a different pressure drop value for each branch.

Displaying the Data in the Form

To display the pressure drop in the modeless form, we simply loop through all the form's controls until we find one named lblPressure, and then set its window text:

#region Send Information to Window Label
 
foreach( System.Windows.Forms.Control control
  in f.Controls.Find( "lblPressure", true ) )
{
  control.Text = Math.Round( 
    data.PressureDrop, 4 ).ToString();
}
#endregion

Caveat

Only use modeless dialogues if you really know what you are doing. In general, modal dialogues are preferable because they are more robust, and easier to understand and implement. Revit is basically treating all external commands as modal, and the API is only partially functional once the command has returned. In this example, the command actually does not return before the modeless form is closed, so that is a non-issue in this case.

Source code

Here is the complete PressureDropTool source code and Visual Studio solution.

Getting Started with the Revit 2010 API

I am back again from a great vacation in Italy which I mostly spent outdoors camping, swimming, cooking, and drinking cappuchino. Yesterday was the Jeûne Fédéral holiday (French) in Neuchâtel. I used that to make a first pass through my overfull email inbox.

Meanwhile, here is a quick summary and overview of the material we have put together so far for getting started with the Revit 2010 API.

Question: Do you have any updated information similar to the getting started material for Revit 2009? I would like to hear about the news and differences between the Revit 2010 and 2009 APIs.

Answer: First of all, for completeness sake, here is the back pointer to the final wrap-up overview of the getting started material for the Revit 2009 API:

• Getting started with the Revit 2009 API

A large part of the material listed there applies to the Revit 2010 API as well.

Additional specific topics related to the Revit 2010 API are covered in subsequent posts:

• Revit 2010 API Introduction – recording and materials of the Revit 2010 API introcution webcast providing a general overview of the API as well as highlighting news and differences to the previous versions.
• The Revit Ribbon API – important for rewriting an external application to make use of the Revit 2010 ribbon.
• The Revit Family API – an overview of the family API including a pointer to the family API webcast recording and materials.
• The Form Creation API – highlights a subset of the family API.
• The Revit MEP API – an overview of the Revit MEP API and the recording and materials of the MEP webcast.

There is an entire blog category appropriately named '2010' which includes all of these and more:

• Revit 2010 API posts

As said, most of the additional resources listed in the discussion on getting started with the Revit 2009 API are also still valid and accessible.

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.

Revit MEP API Webcast

Here is a last-minute reminder to register for the Revit MEP API webcast that we are holding on Thursday August 27^th. You still have 36 hours time until it begins, starting now. To register, you can visit the ADN or Autodesk Developer Network ADN DevTech API training schedule, filter for Revit MEP API, and click on the register link. This webcast is open to all developers, regardless of ADN membership.

I am still very busy preparing the material :-)

Fixing RvtMgdDbg for MEP Connectors

Still working on preparations for the MEP webcast mentioned last week, I notice that RvtMgdDbg is having trouble displaying the connectors on electrical components, throwing an exception saying

Angle is available only for connectors of DomainHavc and DomainPiping.

The method I describe here to fix this problem can be used by anyone who runs into a problem with RvtMgdDbg. It is not limited to the case of MEP connectors, and intended more as an example and a how-to on how to fix RvtMgdDbg to display specific information that you are interested in.

Luckily, RvtMgdDbg is provided in source code format, and everybody can debug it and fix problems for themselves as they see fit. In my case, I debugged the RvtMgdDbg code and traced the problem to the implementation of the overloaded method Stream( ArrayList data, Connector connector ) in the module Snoop > CollectorExts > CollectorExtMEP.cs. The fix is to add an exception handler to the offending property. In this case, the original code simply went ahead and blindly accessed the Angle property:

data.Add( new Snoop.Data.Double( "Angle", connector.Angle ) );

As the exception message says, this access is prohibited unless the connector is defined for the HVAC or piping domain. I therefore added a check to test the connector domain before accessing it, and the updated code now reads:

if( Domain.DomainHvac == connector.Domain 
  || Domain.DomainPiping == connector.Domain )
{
  data.Add( new Snoop.Data.Double( "Angle", 
    connector.Angle ) );
}

That solves that little problem.

Another way to handle this would be to simply encapsulate the offending line of code into its own individual little exception handler, but that would add considerable unnecessary execution overhead. Remember, an exception should be used only for unexpected, exceptional circumstances. If a property is expected to fail under certain circumstances, then these should be caught using traditional and more effective means.

Unfortunately, there are quite a few more properties on the connector class which are similarly limited and throw exceptions if called under invalid circumstances, so the method Stream(ArrayList data, Connector connector) could use quite a few additional corrections. For instance, the Radius property may only be queried in the case of a connector with a round cross section.

Since there are so many properties and I do not want to add individual checks for each of them, I have actually resorted to adding the individual exception handlers I mentioned above to each property for the time being, simply in order to use RvtMgdDbg for electrical connectors right away with no further ado.

I encapsulated each line of code accessing a property into an exception handler using the Visual Studio regular expression replacement feature, searching for a regular expression like this:

{data\.Add.*, connector\.}{[^\.\)]*}{[\)\.].*}\n

The replacement code looks like this:

try\n{\n\1\2\3\n}\ncatch\n{\nDebug.Print( "\2: "+ex.Message );\n}\n

Visual Studio automatically adds the proper indenting for me if I cut out the generated code and then paste it right back into the same place again.

For example, here is the unprotected call to access the AssignedDuctFlowConfiguration property:

  data.Add( new Snoop.Data.String( 
    "Duct flow configuration type", 
    connector.AssignedDuctFlowConfiguration.ToString() ) );

The result of executing the regular expression search and replace operation on that single line of code is to convert the unprotected property access to one encapsulated within its own exception handler. Here is the resulting protected AssignedDuctFlowConfiguration property access:

  try
  {
    data.Add( new Snoop.Data.String( 
      "Duct flow configuration type", 
      connector.AssignedDuctFlowConfiguration.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedDuctFlowConfiguration: " 
      + ex.Message );
  }

Here is the complete code of my modified version of the overloaded method Stream( ArrayList data, Connector connector ):

private void
Stream(ArrayList data, Connector connector)
{
  data.Add(new Snoop.Data.ClassSeparator(typeof(Connector)));
 
  try
  {
    data.Add( new Snoop.Data.Enumerable( "All refs", connector.AllRefs ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AllRefs: " + ex.Message );
  }
  if( Domain.DomainHvac == connector.Domain 
    || Domain.DomainPiping == connector.Domain )
  {
    data.Add( new Snoop.Data.Double( "Angle", connector.Angle ) );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Duct flow configuration type", connector.AssignedDuctFlowConfiguration.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedDuctFlowConfiguration: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Duct loss method type", connector.AssignedDuctLossMethod.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedDuctLossMethod: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned fixture units", connector.AssignedFixtureUnits ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedFixtureUnits: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned flow", connector.AssignedFlow ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedFlow: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Assigned flow direction", connector.AssignedFlowDirection.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedFlowDirection: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned flow factor", connector.AssignedFlowFactor ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedFlowFactor: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned K coefficient", connector.AssignedKCoefficient ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedKCoefficient: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned loss coefficient", connector.AssignedLossCoefficient ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedLossCoefficient: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Assigned pipe flow configuration", connector.AssignedPipeFlowConfiguration.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedPipeFlowConfiguration: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Assigned pipe loss method", connector.AssignedPipeLossMethod.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedPipeLossMethod: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned pressure drop", connector.AssignedPressureDrop ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedPressureDrop: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Coefficient", connector.Coefficient ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Coefficient: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Object( "Connector manager", connector.ConnectorManager ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "ConnectorManager: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Connector type", connector.ConnectorType.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "ConnectorType: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Object( "Coordinate system", connector.CoordinateSystem ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "CoordinateSystem: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Demand", connector.Demand ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Demand: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Direction", connector.Direction.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Direction: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Domain", connector.Domain.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Domain: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Duct system type", connector.DuctSystemType.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "DuctSystemType: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Electrical system type", connector.ElectricalSystemType.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "ElectricalSystemType: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Flow", connector.Flow ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Flow: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Height", connector.Height ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Height: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Bool( "Is connected", connector.IsConnected ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "IsConnected: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Bool( "Is movable", connector.IsMovable ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "IsMovable: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Object( "MEP system", connector.MEPSystem ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "MEPSystem: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Xyz( "Origin", connector.Origin ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Origin: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Pipe system type", connector.PipeSystemType.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "PipeSystemType: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Pressure drop", connector.PressureDrop ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "PressureDrop: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Velocity pressure", connector.VelocityPressure ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "VelocityPressure: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Width", connector.Width ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Width: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Radius", connector.Radius ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Radius: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Shape", connector.Shape.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Shape: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Object( "Owner", connector.Owner ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Owner: " + ex.Message );
  }
}

If you wish to examine the truncated overly long lines, you can copy and paste them to an editor.

Running the modified version of RvtMgdDbg and selecting an electrical connector produces the following list in the Visual Studio debug output window of all the properties that are throwing exceptions:

AssignedDuctFlowConfiguration: Assigned duct flow configuration is available only for connectors of DomainPiping.
AssignedDuctLossMethod: Assigned duct loss method is available only in connectors of DomainHvac.
AssignedFixtureUnits: Assigned fixture units available only for connectors of DomainPiping.
AssignedFlow: Assigned flow is available only for connectors of DomainHavc or DomainPiping.
AssignedFlowDirection: Assigned flow direction is available only for connectors of DomainHavc and DomainPiping.
AssignedFlowFactor: Assigned flow factor is available only for connectors of DomainPiping or DomainHvac.
AssignedKCoefficient: Assigned KCoefficient is available only for connectors of DomainPiping.
AssignedLossCoefficient: Assigned loss coefficient is available only for connectors of DomainHavc.
AssignedPipeFlowConfiguration: Assigned pipe flow configuration is available only for connectors of DomainPiping.
AssignedPipeLossMethod: Assigned pipe loss method is available only for connectors of DomainPiping.
AssignedPressureDrop: Assigned pressure drop is available only for connectors of DomainHavc and DomainPiping.
Coefficient: Coefficient is available only for connectors of DomainHavc and DomainPiping.
CoordinateSystem: Coordinate System is available only for connectors of PhysicalConn.
Demand: Demand is available only for connector of DomainPiping.
Direction: Direction is available only for connectors of DomainHvac and DoaminPiping.
DuctSystemType: Duct system type is available only for connectors of DomainHvac.
ElectricalSystemType: Electrical system type is available only for connectors of DomainElectrical.
Flow: Flow is available only for connectors of DomainHavc and DomainPiping.
Height: The shape of the connector is not rectangular.
IsConnected: Connection status is available only for connectors of PhysicalConn type.
Origin: Origin is available only for connectors of PhysicalConn type.
PipeSystemType: Pipe system type is available only for connectors of DomainPiping.
PressureDrop: Pressure drop is available only for connectors of DomainHavc and DomainPiping.
VelocityPressure: Velocity pressure is available only for connectors of DomainHavc and DomainPiping.
Width: The shape of the connector is not rectangular.
Radius: The shape of the connector is not round.

Again, copy and paste to an editor to see the complete truncated lines.

Since each exception caught by an invalid property access is caught individually and processing can continue with an attempt at the next property, the other desired result is that the property window is now successfully populated and displayed with the remaining properties that have not thrown an exception:

As pointed out above, this is only a partial and temporary fix. In the long run, the individual exception handlers should be replaced by if clauses, as done for the Angle property.

MEP Sample Ribbon Panel

I am preparing our upcoming Revit MEP API webcast to be held on Thursday August 27^th. To register, you can go to the Autodesk Developer Network (ADN) DevTech API training schedule and filter for Revit MEP API.

One thing I did today was to update our MEP sample external application from the Revit 2009 menu-based user interface to a 2010-style custom ribbon panel.

Here is the code for the AddMenu method that was being used in Revit 2009 to create a custom menu:

private static void AddMenu( ControlledApplication app )
{
  const string m = "mep.Cmd"; // namespace and command prefix
  string path = System.Reflection.Assembly.GetExecutingAssembly().Location;
  Autodesk.Revit.MenuItem rootMenu = app.CreateTopMenu( "ME&P API Samples" );
  MenuItem.MenuType mt = MenuItem.MenuType.BasicMenu;
  rootMenu.Append( mt, "&Assign flow to terminals", path, m + "AssignFlowToTerminals" );
  rootMenu.Append( mt, "&Change size", path, m + "ChangeSize" );
  rootMenu.Append( mt, "&Populate CFM per SF on spaces", path, m + "PopulateCfmPerSf" );
  rootMenu.Append( mt, "&Reset demo", path, m + "ResetDemo" );
  rootMenu.Append( MenuItem.MenuType.SeparatorMenu );
  rootMenu.Append( mt, "Electrical &System Browser", path, m + "ElectricalSystemBrowser" );
  rootMenu.Append( mt, "Electrical &Hierarchy", path, m + "ElectricalHierarchy" );
  rootMenu.Append( mt, "Electrical Hierarchy &2", path, m + "ElectricalHierarchy2" );
  rootMenu.Append( mt, "&Unhosted elements", path, m + "UnhostedElements" );
  rootMenu.Append( MenuItem.MenuType.SeparatorMenu );
  rootMenu.Append( mt, "A&bout...", path, m + "About" );
}

To see the overly long lines, you can copy and paste to an editor.

AddMenu is called from the external application OnStartup method.

How can this be easily converted to a ribbon panel?

Well, note a couple of basic things here:

• All the command implementation classes reside in the namespace mep and have the prefix "Cmd". Therefore, the variable 'm' is defined as "mep.Cmd" and used to prefix each command class name stem.
• All commands reside in the same assembly as the external application, so they all have the same assembly path as the currently executing assembly.
• A new top level menu with the text 'MEP API Samples' is created.
• The menu items for the individual commands are added one by one, grouped by separators into HVAC, electrical, and the about groups.

Converting this to a ribbon panel is pretty straightforward. The basics and all possibilities provided by the Revit API for creating your own ribbon panels are demonstrated by the Revit SDK sample Ribbon.

Here is the code for the new AddRibbonPanel method, also called from the external application OnStartup method, which creates an equivalent custom ribbon panel:

static void AddRibbonPanel(
  ControlledApplication a )
{
  const string m = "mep.Cmd"; // namespace and command prefix
  string path = Assembly.GetExecutingAssembly().Location;
 
  string[] text = new string[] {
    "Assign flow to terminals",
    "Change size",
    "Populate CFM per SF on spaces",
    "Reset demo",
    "Electrical System Browser",
    "Electrical Hierarchy",
    "Electrical Hierarchy 2",
    "Unhosted elements",
    "About..."
  };
 
  string[] classNameStem = new string[] {
    "AssignFlowToTerminals",
    "ChangeSize",
    "PopulateCfmPerSf",
    "ResetDemo",
    "ElectricalSystemBrowser",
    "ElectricalHierarchy",
    "ElectricalHierarchy2",
    "UnhostedElements",
    "About"
  };
  //
  // create three stacked buttons for the 
  // HVAC, electrical and about commands respectively:
  //
  RibbonPanel panel = a.CreateRibbonPanel(
    "MEP Sample" );
 
  PulldownButtonData d1 = new PulldownButtonData(
    "Hvac", "HVAC" );
 
  d1.ToolTip = "HVAC Commands";
 
  PulldownButtonData d2 = new PulldownButtonData(
    "Electrical", "Electrical" );
 
  d2.ToolTip = "Electrical Commands";
 
  PushButtonData d3 = new PushButtonData(
    classNameStem[8], text[8], path, m + classNameStem[8] );
 
  d3.ToolTip = "About the HVAC and Electrical MEP Sample.";
 
  List<RibbonItem> ribbonItems = panel.AddStackedButtons(
    d1, d2, d3 );
  //
  // add subitems to the HVAC and electrical pulldown buttons:
  //
  PulldownButton pulldown;
  PushButton pb;
  int j;
 
  for( int i = 0; i < 8; ++i )
  {
    j = i < 4 ? 0 : 1;
    pulldown = ribbonItems[j] as PulldownButton;
 
    pb = pulldown.AddItem( text[i], path,
      m + classNameStem[i] );
 
    pb.ToolTip = text[i];
  }
}

The procedure to create and populate the panel is straightforward:

• We define the external command name prefix and assembly path like before.
• The command name stems and menu item texts are stored in two string arrays.
• A new ribbon panel is created.
• Two pulldown buttons to group the HVAC and electrical commands are added to the panel.
• One push button for the about box command is added.
• The string arrays of menu item texts and class name stems are iterated.
• A ribbon item is created for each command.

Here is the panel as it appears when dragged out of the ribbon to float freely:

Here is the complete source code and Visual Studio solution for the MEP sample application in its current state. We will be discussing more details of its implementation in the coming weeks.

Here is a related question that just came up:

Ribbon Panel Image Resources

Question: I want to populate my Revit add-in ribbon panel with images which I obtain from the resources with a method like this:

internal static System.Drawing.Bitmap door_button {
  get {
    object obj = ResourceManager.GetObject(
      "door_button", resourceCulture);

    return ((System.Drawing.Bitmap)(obj));
  }
}

The object type of the image to assign to a button for the ribbon toolbar is System.Windows.Media.ImageSource. I tried the same approach as above, to provide a method that returns an object of this type and cast to it to the required type before returning. This does not work, even though the compiler does not complain. How can I cast between these types, or how else can I retrieve an image of the type System.Windows.Media.ImageSource from the resources, so that I do not have to have the actual image file (png or bitmap) to be distributed with the application?

I see that the method "ResourceManager.GetObject()" returns an object of type "System.Drawing.Bitmap", but the data type to be assigned to a ribbon-button is "BitmapImage". I do not see any common base types or a constructor for this class that allows an object of type "System.Drawing.Bitmap" or any derived class from it, so I do not see how to convert between the types. However, investigating the classes in the class browser I have found a method "FromResource" for the Bitmap class, but I have not seen an example on how to use it.

Answer: When I look at the Revit SDK sample Ribbon, I see it using the class System.Windows.Media.Imaging.BitmapImage to define the external application ribbon images.

I do agree that retrieving the bitmap image from the resources is a much cleaner solution than the one used in the Ribbon sample.

System.Windows.Media.ImageSource is an abstract class, so you will never be able to obtain an instance of that from anywhere.

You can open the PresentationCore assembly in the Visual Studio Object Browser, navigate to the class System.Windows.Media.Imaging.BitmapImage, and open its 'Base Types' sub node. That will show you that it is derived from BitmapSource, which is derived from ImageSource.

The Ribbon sample simply uses the BitmapImage constructor to create a BitmapImage which also constitutes an ImageSource.

Now back to your main question, how to convert from the Bitmap returned from the resource manager to the BitmapImage required by the Revit ribbon API.

I googled for "cast Bitmap BitmapImage" and found various useful hits. Based on these, this is the solution that I ended up with, which I tested in a simple console application:

static void Main( string[] args )
{
  Bitmap a = Resource1.Image1;
 
  MemoryStream ms = new MemoryStream();
  a.Save( ms, ImageFormat.Png );
 
  BitmapImage b = new BitmapImage();
  b.BeginInit();
  b.StreamSource = ms;
  b.EndInit();
}

By the way, another example of using resources and utilising the .NET framework ResourceManager class to manage them is provided by the PowerCircuit Revit SDK sample.