Yesterday I discussed the Revit 2013 MEP API and the external services framework.
In preparation for my Revit MEP API presentation at the upcoming AEC DevCamp in Boston in June, I also migrated the ADN MEP API sample AdnRme to Revit MEP 2013.
The initial flat migration was extremely straightforward with zero code changes required.
I obviously had to change the Revit API assembly references, which forces an update of the .NET framework version to 4.0. After bumping the framework version, the whole solution immediately compiled with zero errors and warnings. I must admit I was a bit surprised.
New One-box Product Type
On loading it, though, I was surprised again, because the add-in ribbon panel was simply not displayed.
Debugging the external application OnStartup method revealed that since I was running and testing it in a one-box flavour of Revit, the product type was not 'MEP' but simply 'Revit'. To fix this, I had to add support for both of those enumeration values to my product type test:
public Result OnStartup( UIControlledApplication a ) { // only create a new ribbon panel in Revit MEP: ProductType pt = a.ControlledApplication.Product; //if( ProductType.MEP == pt ) // 2012 if( ProductType.MEP == pt || ProductType.Revit == pt ) // 2013 { AddRibbonPanel( a ); return Result.Succeeded; } return Result.Cancelled; }
With that little change in place, everything works fine and my ribbon panel shows up as expected:
Actually, for full-fledged support of the new runtime discipline switching, I could add more flexible enabling and disabling of my buttons, if I wanted to, for instance by dynamically hiding this application when the MEP discipline is not enabled.
Here is the 'About' box, automatically populated with properties harvested from the .NET assembly company, copyright, description, product, title and version and attributes, explaining briefly what this sample is about:
History and Functionality
By the way, although I have been demonstrating and using this sample for many years now, I have still not described its functionality in detail here in the blog, so maybe that is something I should do right now.
Several descriptions have been made publicly available in the past, though, for instance in the materials for my Autodesk University 2011 virtual class CP4453 Everything in Place with Autodesk Revit MEP Programming, covering both the Revit MEP 2012 API features and the Revit MEP API in general.
Before that, I already published the code here on the blog for Revit MEP 2012 and previous versions, and at previous Autodesk University and AEC DevCamp events.
The AdnRme sample demonstrates several Revit MEP API aspects, in two separate main areas:
- HVAC air terminal analysis and sizing.
- Hierarchical display of an electrical system.
It also demonstrates some Revit and .NET API aspects not directly related to the MEP API, such as:
- External application implementation.
- About box, automatically populated using .NET assembly properties.
- Progress bar.
AdnRme implements an external application to define a custom user interface to access the sample commands, as you can see from the ribbon panel shown above. The about box is also shown above.
The progress bar may be useful in a large project, since the processing of a large number of elements may take a noticeable amount of time, and is implemented using a standard .NET modeless form:
HVAC Air Terminal Analysis and Sizing Sample
The HVAC part of the MEP sample was originally implemented based on Revit 2008, before the advent of any MEP-specific API at all, using pure generic Revit element and parameter access to analyse and modify the HVAC duct system.
It supports a typical HVAC engineering workflow including the following tasks:
- Placement and sizing of air distribution ducts and terminals.
- Analysis and verification of results.
In a little more detail, the workflow might look like this:
- Manually lay out air terminals.
- Run heating and cooling load analysis.
- Based on load analysis, assign flow to terminals.
- Based on terminal flow, size air terminals.
- Validate design; a common check figure uses air flow per surface area.
The MEP HVAC sample was originally implemented for Revit 2008 and based on room elements, since spaces had not yet been introduced back then. It was modified for RME 2009 to use spaces.
It implements the following four commands to support the HVAC engineering workflow described above. The first three support the actual workflow itself, the fourth cleans up and resets the data manipulated by them:
- Assign flow to terminals.
- Change air terminal size.
- Calculate and display flow density as colour fill to verify design by air flow per surface area.
- Reset demo.
This workflow is exercised in the following simple office building sample model with a place holder duct system in place:
Here it is in plan view:
The progress of the steps is displayed by four schedules set up in the sample model:
Initially, all the 51 diffusers are the same:
The 33 spaces have calculated and specified supply air flows defined, but no actual flow:
The CFM per SF parameter in the right-hand column is defined to generate a colour schema at the end to verify the results visually at a glance, and is currently still set to zero.
The air terminals have not yet been properly analysed and sized:
Their flow and actual supply air flow is still zero:
Executing the commands in the proper sequence fixes all this:
- Assign flow to terminals: calculate the required flow per terminal by dividing the required flow for the space by the number of terminals, and assigning the resulting value to each terminal via its Flow parameter.
- Change air terminal size: for each diffuser type, determine its minimum and maximum flow. Select the type that ensures that the actual flow lies between these two.
- Calculate and display flow density as colour fill to verify design by air flow per surface area: calculate the CFM per SF using the built-in parameters ROOM_ACTUAL_SUPPLY_AIRFLOW_PARAM and ROOM_AREA and set the "CFM per SF" parameter accordingly.
The schedules are all updated, and the predefined colour fill displays and enables visual verification of the results:
Electrical Hierarchy Sample
Later during the lifetime of this sample, the electrical hierarchy functionality was added, initially based on non-MEP-specific analysis of parameter values to determine the system structure, later rewritten and significantly simplified by accessing the MEP connectors for this task instead.
In a way, the electrical hierarchy part is closely related to the TraverseSystem duct system SDK sample, which traverses a duct system by moving through its elements from predecessor to successor element through the connectors and storing the resulting tree data in an HTML file.
The AdnRme electrical sample does the same and displays the result in a tree view form instead:
It actually determines and displays the hierarchical structure of the electrical systems in the model in several different ways. Its focus is to:
- Traverse the electrical system
- Reproduce the system browser data structure in a tree view
- Determine and display the complete connection hierarchy in a tree view
The standard RME system browser displays electrical components in a three-level flat list, and the complete hierarchical structure of the connection tree is not immediately apparent. This sample inspects the electrical systems and reproduces the structure and information displayed by the system browser as well as the full connection hierarchy. It implements the following commands:
- CmdElectricalConnectors
- CmdElectricalSystemBrowser
- CmdUnhostedElements
The first two analyse the electrical system hierarchical structure and present it to the user in a tree view in a modeless dialogue, either in the full hierarchical structure, or in the three-tier structure used by the system browser; the third detects and lists un-hosted elements.
The form displaying the full electrical system hierarchical structure is shown above. Besides the hierarchical structure, it also presents a list of panels and devices on the left-hand side and highlights them in bold in the hierarchical tree display.
Clicking on a panel node in the left-hand list redisplays the tree on the right, with all the tree nodes except the selected panel or device collapsed. Here we select the panel H-2:
Here, transformer T1 is selected instead:
Being modeless, the form remains visible and can be navigated after the command has terminated. You can leave the form open and switch back and forth between it and Revit to explore the electrical system simultaneously from both points of view. Note, however, that updates to the model will not be reflected in the dialogue until the command is re-executed. A sample model elec_project.rvt is provided. Also note that this was originally implemented a long time ago and does not take all of Arnošt's recent advice on interaction with a modeless dialogue and avoiding too much use of the Idling event into account. On the other hand, the modeless form never attempts to make any use whatsoever of the Revit API, so there should be nothing to worry about in this case.
Besides the connection hierarchy tree, the electrical sample also implements these other commands:
- Obsolete pre-connector approach
- Three-tier system browser structure
- Find un-hosted elements
The obsolete pre-connector parameter-based approach is still included in the source code, in the C# module CmdElectricalHierarchy2.cs, but has been removed from the user interface.
The system browser three-tier structure is also displayed in a tree structure, like this:
The un-hosted element command simply displays a Windows message box listing all elements, which may well overflow the screen in a large untidy model:
As said, I documented some other aspects of this sample in the last few years' Revit MEP API classes at Autodesk University and the AEC DevCamp two years back, so if you really want to know still more, you might be lucky there. I think this just about covers it, though, actually more than enough.
Here is adn_rme_2013.zip containing the full Visual Studio solution, source code, add-in manifest and electrical and HVAC sample models to run this and play with. Enjoy.
Many thanks once again to Martin Schmid for motivating and helping me set up the HVAC sample back then, many years ago, and many other inspiring impulses since!
US Army Corps of Engineers Revit Templates
Here is a little piece of news that just happened to come past my way and might be of interest to you as well, even though it is not API related:
The US Army Corps of Engineers ASACE has released version 1 of their Revit Architecture, Structure, MEP templates.
These templates were developed to standardize MILCON production documentation and deliverables created by in-house USACE staff to reduce project start-up and configuration lead times, improve the quality and consistency of the contract deliverables and increase the adoption of BIM in general.
If you are interested in this fiscal year's opportunities with USACE, here are some interesting links: