Revit MEP Programming: All Systems Go

Jeremy Tammik
Principal Developer Consultant

2012 Autodesk
About the Presenter

Jeremy Tammik
Principal Developer Consultant
Developer Technical Services
EMEA, Autodesk SARL

Jeremy is a member of the AEC workgroup of the Autodesk Developer Network ADN team,
providing developer support, training, conference presentations, and blogging on the Revit API.
He joined Autodesk in 1988 as the technology evangelist responsible for European developer
support to lecture, consult, and support AutoCAD application developers in Europe, the U.S.,
Australia, and Africa. He was a co-founder of ADGE, the AutoCAD Developer Group Europe, and
a prolific author on AutoCAD application development. He left Autodesk in 1994 to work as an
HVAC application developer, and then rejoined the company in 2005.
Jeremy graduated in mathematics and physics in Germany, worked as a teacher and translator,
then as a C++ programmer on early GUI and multitasking projects. He is fluent in six European
languages, vegetarian, has four kids, plays the flute, likes reading, travelling, theatre
improvisation, yoga, carpentry, loves mountains, oceans, sports, dancing, and especially climbing.
2012 Autodesk
Class Summary

Overview of the Revit MEP API

MEP API enhancements in Revit 2013

Working programmatically with Revit MEP models

Overview of available Revit MEP API samples

Prerequisites: we assume prior knowledge of

How to program in .NET

The basics of the generic Revit API

Revit MEP product usage

2012 Autodesk
Learning Objectives
At the end of this class, you will be able to:

Understand and use the Revit MEP 2013 API enhancements

Analyze, create, manage and modify electrical, HVAC and plumbing
models, systems, and components programmatically

Understand and reuse Revit SDK and ADN sample functionality

2012 Autodesk
Agenda

Introduction

Analysis

Hierarchical systems and connectors

Electrical

HVAC and plumbing

The Revit MEP 2013 API

Sample applications

Learning more

2012 Autodesk
Introduction

2012 Autodesk
Acronyms

ADN Autodesk Developer Network

AEC Architecture, Engineering, Construction

API Application Programming Interface

BIM Building Information Model

GUI Graphical User Interface

HVAC Heating, Ventilation, and Air Conditioning

MEP Mechanical, Electrical, and Plumbing

RAC Revit Architecture

RME Revit MEP

RST Revit Structure

SDK Software Development Kit

UI User Interface

2012 Autodesk
MEP Application Requirements

Mechanical, electrical and plumbing domains

M is for HVAC, i.e. heating, ventilation and air conditioning

Model analysis tools

Physical, thermal, environmental etc.

Building codes and regulations

Geometrical relationships

MEP project information

Green Building XML, gbXML

Spaces and zones

BIM component and data access

Systems, components, properties and parameters

Creation and modification

Traversal and analysis
2012 Autodesk
The Generic Revit API

Basic Revit API is generic

All flavours use the same Revit API .NET assemblies

Specific additional features exist for each flavour, e.g.

Room-related functionality in Revit Architecture

Access to the analytical model in Revit Structure

Access to the MEP model in Revit MEP

Onebox supports all in one box

Runtime discipline switching

ProductType Architecture, Structure, MEP, Revit

2012 Autodesk
Revit MEP API Evolution

Generic element and parameter access can always be used

Revit 2008 provided no MEP-specific API

Revit 2009 introduced MEP-specific API support

MEP model property, space and zone, electrical and mechanical equipment, lighting
device and fixture, connector, electrical system

Revit MEP 2010 mechanical

MEP namespace, support for HVAC and piping systems

Revit MEP 2011 electrical

Conduit, cable tray, panel schedule

Revit MEP 2012 mechanical

Pipe settings and sizes, placeholder elements, insulation and lining

Revit MEP 2013 mechanical and analysis

Routing preferences, analysis and calculation enhancements, new and updated APIs

2012 Autodesk
Analysis

2012 Autodesk
MEP Project Info and EnergyDataSettings

EnergyDataSettings object represents gbXML project info

Manage > Project Settings > Project Information > Energy Data

Access via EnergyDataSettings.GetFromDocument method

Define settings for gbXML export, heating and cooling load calculations,
conceptual energy analysis

For project location use Document.ActiveProjectLocation

Green Building XML export

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

2012 Autodesk
Spaces and Zones

Architectural rooms are unsuitable for MEP analysis

Wrong height, often too large for analysed region

MEP uses space instead of room, and zone to manage spaces

Rooms can be subdivided into exterior and interior subspaces

AddSpaceAndZone SDK sample

Programmatic creation and management of spaces and zones

FamilyInstance class has Room and Space properties
FamilyInstance fi; // get a family instance
Space space = fi.Space; // query space containing it
Space space2 = fi.get_Space( phase ); // space in a specific
phase

2012 Autodesk
Model Inspection Utilities

Determine component location, space adjacency analysis, etc.

Volumes, rooms and spaces

FamilyInstance.Space determines space containing family instance

Room.IsPointInRoom determines if a point is in a room volume

Space.IsPointInSpace determines if a point is in a space volume

GetRoomAtPoint and GetSpaceAtPoint return room or space containing point

Element filters by intersection, Boolean operations, etc.

BoundingBoxIntersectsFilter, BoundingBoxIsInsideFilter, BoundingBoxContainsPointFilter,
ElementIntersectsElementFilter, ElementIntersectsSolidFilter

Ray intersection

ReferenceIntersector class, ex FindReferencesWithContextByDirection method

Shoot a ray through the model, given a starting point and direction vector

Return an array of references of intersected elements and faces

AvoidObstruction, FindColumns, MeasureHeight, RayTraceBounce SDK samples

2012 Autodesk
Revit 2013 ReferenceIntersector Class

Constructor specifies target elements, target type and 3D view

Elements specified by ElementId, ElementIdSet , ElementFilter

Target type can be elements, meshes, edges, curves, faces

ReferenceIntersector( <elements>, FindReferenceTarget, View3d )

Call Find or FindNearest to cast a ray given origin and direction

Returns references intersecting ray, or closest to origin

Find( XYZ origin, XYZ direction )

FindNearest( XYZ origin, XYZ direction )

2012 Autodesk
Conceptual Energy Analysis API

Energy analysis on conceptual design models

New overload of Document.Export method taking
MassGBXMLExportOptions argument

Create a gbXML file containing energy analysis elements generated
from conceptual mass family instances

2012 Autodesk
Detailed Energy Analysis Model API

Produce analytical thermal model from physical building model

Retrieve energy analysis detail model and present as tree view

Access Export to gbXML, Heating and Cooling Loads data

Analytical thermal model

Composed of volumetric elements: spaces, zones, planar surfaces

Created and initialised by calling EnergyAnalysisDetailModel.Create()

Methods GetAnalyticalSpaces, Surfaces, Openings, ShadingSurfaces

SDK sample Analysis > EnergyAnalysisModel

2012 Autodesk
Hierarchical Systems and Connectors

2012 Autodesk
Hierarchical System Structure and MEP Model

MEP systems consist of hierarchically connected components

Many components are represented using family instances

Connectors can link neighbouring components and transfer info

Top level node is MEP system

Represented by MEPSystem class, with derived classes ElectricalSystem,
MechanicalSystem, PipingSystem

Family instance provides MEPModel property

MEPModel has ConnectorManager and ElectricalSystems properties

Derived classes include ElectricalEquipment, LightingDevice, LightingFixture,
MechanicalEquipment, MechanicalFitting

2012 Autodesk
Connectors

Family editor connection elements

Independent elements for defining connectors

Used to model library parts in family context

Specialised derived classes for duct, pipe and electrical connectors

Connector class

Used to represent connections in the Revit BIM project context

Part of MEP component, not independent Revit database element

Logical connectors

Used in electrical domain

Cables and wires are possibly not specified

Enables traversal of connected
electrical system hierarchies

Physical connectors

Connect neighbouring components physically

Transmit sizing dimensions and flow information

2012 Autodesk
Electrical

2012 Autodesk
Electrical System Hierarchy

Three-tier recursive hierarchy, cf. electrical system browser

Panel > systems or circuits > circuit elements, may be panels

Logical connections between components

Wires are annotation elements

System can be traversed through connectors

Connectivity information also available in element parameters

Electrical samples

PowerCircuit SDK sample shows creation and editing power circuits

PanelSchedule SDK demonstrates use of the electrical panel schedule API

AdnRme electrical sample demonstrates traversal using both MEP connectors
and generic parameters (much harder)

2012 Autodesk
HVAC and Plumbing

2012 Autodesk
HVAC and Piping Hierarchy

Systems manage the top level system properties

Ducts and pipes define the main flow elements

Fittings implement bends and branches in the system

Connectors hook up the ducts, pipes and fittings

2012 Autodesk
Systems

MechanicalSystem and PipingSystem classes

Access to equipment, connectors and system type

Access to system properties such as flow and static pressure

DuctNetwork and PipeNetwork properties access system contents

Ducts and fitting elements in no particular order

Does not include terminals or equipments

Query connector managers for traversal in flow direction

TraverseSystem SDK sample

2012 Autodesk
Duct and Pipes

Represented by Duct, FlexDuct, Pipe and FlexPipe classes

Derived from MEPCurve

Provide read access to duct properties, types, and geometry

Change duct or pipe type

Move duct or pipe

Use Move method rather than Location

Layout duct or pipe

Driven by two points, point and connector, or two connectors

2012 Autodesk
Fittings

Represented by standard RFA family instances

Created using dedicated creation doc New*Fitting methods

Elbow, Tee, Cross, Takeoff, Transition, and Union

Access fitting properties, shape and dimensions through the
FamilyInstance.MEPModel property

2012 Autodesk
Connectors

Read duct, pipe, and fitting connector properties

Flow, Coefficient, Demand

Access physical connector properties

Origin, Angle, Height, Width, Radius

Read and write assigned connector properties

The fitting connectors define the properties

Flow, Flow Configuration, Coefficients, Loss Method

Change connector size and location

Connect and disconnect

2012 Autodesk
Element Creation

Methods on Autodesk.Revit.Creation.Document

Create New Systems

NewMechanicalSystem, NewPipingSystem

Create New Elements

NewDuct, NewFlexDuct, NewPipe, NewFlexPipe

Create New Fittings

New...Fitting for Cross, Elbow, TakeOff, TeeFitting, Transition, Union

New classes Conduit, CableTray provide static Create methods

Connector elements

Created in the family context using methods on FamilyItemFactory

Accessed through the Document.FamilyCreate property

NewDuctConnector, NewPipeConnector, NewElectricalConnector

2012 Autodesk
The Revit MEP 2013 API
and the past few releases as well...

2012 Autodesk
Revit MEP 2011 API Enhancements

New classes for cable tray and conduit

Pipe to conduit converter sample

Panel schedules

API access and PanelSchedule SDK sample

Other Enhancements

EnergyDataSettings

Validation in ElectricalSystem Properties

WireMaterialType, InsulationType, TemperatureRatingType

DuctConnector, PipeConnector, ElectricalConnector

Demand Factor and Load Classifications

2012 Autodesk
Revit MEP 2012 API Enhancements

Pipe settings and sizes

Placeholder ducts and pipes

Duct and pipe insulation and lining

Small Enhancements and Changes

MEP related APIs

Detailed Energy Analysis

Conceptual Energy Analysis

2012 Autodesk
Revit MEP 2013 Product Features

Routing preferences

Calculation enhancements

MEP centrelines

New MEP properties

Enhanced analysis and simulation functionality

2012 Autodesk
MEP 2013 API Enhancements

Routing preferences

MEP pressure loss calculation sections

Fluid viscosity and density friction properties

Thermal properties

External services

And more...

2012 Autodesk
Routing Preferences API Access

Select preferred fitting types for various sizes and materials

Set routing preference policies for end users

Query fittings and segments used for given size criteria

RoutingPreferenceManager class

Manages routing preference rules for segments and fittings

Query fitting or segment chosen by Revit for a given size condition

MEPCurveType RoutingPreferenceManager property

Access main routing preferences object for a given MEPCurve type

Currently only PipeType and DuctType support routing preferences

Use demonstrated by RoutingPreferenceTools SDK sample

2012 Autodesk
Routing Preference Helper Classes

RoutingCriterionBase and PrimarySizeCriterion

Criteria for fitting and segment selection based on min max size constraints

RoutingPreferenceRule

Manage one segment or fitting preference

RoutingCondition and RoutingConditions

RoutingPreferenceManager.GetMEPPartId input to select fittings and segments

Segment and PipeSegment

Represent a length of MEPCurve of specific material and set available sizes

Subclass representing a length of pipe

RoutingPreferenceRuleGroupType enumeration

Types of routing items managed by routing preference rules

Elbows, Junctions, Crosses, Transitions, Unions, MechanicalJoints, Segments,
TransitionsRectangularToRound, TransitionsRectangularToOval, TransitionsOvalToRound

2012 Autodesk
Routing Preference Usage

Routing preferences choose first symbol in rule list matching criteria

Set size criteria to ensure a later symbol is chosen for a given scenario

Temporarily re-order rules using RemoveRule and AddRule methods

2012 Autodesk
Flow Analysis Sections

MEPSection base class for duct and pipe sections

Support for pressure loss calculation

Represent a series of connected elements

Ducts or pipes, fittings, terminals and accessories

All section members have same flow analysis properties

Flow, Size, Velocity, Friction and Roughness

An element can belong to multiple sections

A tee fitting with three connectors usually belongs to three sections

A tap will divide a duct or pipe segment into two separate sections

2012 Autodesk
Fluid Viscosity and Density

More precise temperature dependant friction calculation

New FluidTemperature class

Represent viscosity and density properties at a given temperature

Extended FluidType class

Provide read-write access to a collection of FluidTemperature objects

Represent fluid properties at various different temperatures

AddTemperature, GetTemperature, RemoveTemperature

GetFluidTemperatureSetIterator

2012 Autodesk
Thermal Properties

New properties on ThermalProperties class

Absorptance, heat transfer, roughness, thermal mass and resistance

Available on BIM elements, e.g. wall, floor, ceiling, roof, door, window, etc.

ThermalAsset class

Thermal properties on materials

Specify using PropertySetElement and SetMaterialAspectByPropertySet

Thermal property control in gbXML export

EnergyDataSettings.IncludeThermalProperties determines whther to include
thermal information from model assemblies and components in gbXML export

Use calculated values or pre-defined values from Constructions.xml:
MEPBuildingConstruction GetBuildingConstructionOverride,
SetBuildingConstructionOverride

2012 Autodesk
More Revit MEP API News

ConnectorProfileType and PartType enumeration changes

ConnectorElement changes and new static creation methods

More LabelUtils access to localized user-visible display strings

Access to panel schedule spare circuit values

Light and Light Group API

ReferenceIntersector class

External services framework

Wrap external service functionality, enable encapsulation, replacement

Basis for future MEP calculations and structural code checking

In place and fully functional, but not yet used, so no examples

2012 Autodesk
Sample Applications

2012 Autodesk
Sample Overview

Revit SDK Samples
AdnRme

AddSpaceAndZone
Electrical System Hierarchy

AutoRoute
HVAC Air Terminal Sizing

AvoidObstruction
Blog

CreateAirHandler
Pipe to Conduit Converter

EnergyAnalysisModel
Cable Tray Creation and Layout

PanelSchedule
Loose Connector Navigator

PowerCircuit
MEP Placeholders

RoutingPreferenceTools

TraverseSystem

2012 Autodesk
AddSpaceAndZone

Retrieve and list existing
spaces and zones

Demonstrates use of an element filter

Create new spaces

For each closed wall loop or space
separation

Demonstrates use of the NewSpaces
method

Create a new zone element

Specified level and phase

Add and remove spaces in a zone

Use the AddSpaces and Remove methods

2012 Autodesk
AutoRoute

Automatically create and route a set of ducts and fittings

Source is the air supply equipment

Sink is two air outlet terminals

Positions can be freely moved

Create a new mechanical system, ducts, fittings and connections

NewMechanicalSystem, NewDuct, NewElbowFitting,
NewTeeFitting and Connector.ConnectTo

Determine the bounding box of all the three elements

Use the middle line or quarter lines on the X and Y axes

Uses.NET framework Trace class to create a log file

2012 Autodesk
AvoidObstruction

Detect and resolve collisions between ducts, pipes, and beams

FindReferencesWithContextByDirection ray cast intersection analysis

Split pipe into segments and insert elbows to reroute detour

2012 Autodesk
CreateAirHandler

Create an air handler with pipe and duct connectors

Check family category to verify mechanical equipment starting point

Use FamilyItemFactory class methods

NewExtrusion, NewPipeConnector, NewDuctConnector

Set proper connector parameters

Use Document.CombineElements to join extrusions

Geometric shape creation is generic

Addition of the connectors is MEP specific

Runs in all flavours of Revit anyway

2012 Autodesk
EnergyAnalysisModel

Retrieve energy analysis detail model and present as tree view

Analytical thermal model generated from physical building model

Similar to Export to gbXML and Heating and Cooling Loads

Analytical thermal model is composed of spaces, zones, planar surfaces

Volumetric elements

Created and initialised by calling EnergyAnalysisDetailModel.Create()

Methods GetAnalyticalSpaces, Surfaces, Openings, ShadingSurfaces

2012 Autodesk
PanelSchedule

Data exchange sample showing use of the Panel Schedule API

PanelScheduleExport read + export panel schedule CSV or HTML

InstanceViewCreation create panel schedule view instance

SheetImport place all panel schedule views on a sheet

2012 Autodesk
PowerCircuit

Operate power circuits, similar to legacy RME Circuit Editor toolbar

Show use of MEPModel and ElectricalSystem classes

Demonstrate handling interactive element selection

Implement toolbar user interface for external command

Use .NET ResourceManager class for image and string resources

Create a new power circuit with selected elements

Edit circuit and add and remove circuit elements

Select or disconnect a circuit panel

2012 Autodesk
RoutingPreferenceTools

Routing preference analysis and reporting

Analyse routing preferences of a given pipe type

Look at all rules and criteria for a given pipe type

Check for common problems

Routing preference builder XML import and export

CommandReadPreferences and CommandWritePreferences

Set project pipe type, fitting, and routing preferences

Export for archival, documentation, and collaboration purposes

Enable users to work with RP data in a shareable XML format

Suitable for reuse in a wide variety of BIM management environments

2012 Autodesk
TraverseSystem

Traverse a mechanical or piping system in the direction of flow

Check MechanicalSystem IsWellConnected property

Dump the traversal results into an XML file

Determine system

Query base equipment as starting point

Query connector manager for connected neighbour elements

Similar approach works for electrical as well, cf. AdnRme sample

2012 Autodesk
AdnRme Sample

Non-SDK sample, included in presentation material

HVAC air terminal analysis and sizing

Hierarchical display of an electrical system

Implements a ribbon panel, about box, and progress bar

2012 Autodesk
AdnRme Electrical Sample

Traverse the electrical system

Reproduce the system browser data
structure in a tree view

Display the complete connection
hierarchy in a tree view

CmdElectricalConnectors is similar to
TraverseSystem SDK sample for ducts

Traversal is also possible using
parameter data instead of connector
manager, but harder

2012 Autodesk
AdnRme HVAC Sample

HVAC Task

Place and size air ducts and terminals

Analysis and verification of results

Commands aligned with HVAC
engineering workflow

Assign flow to terminals

Change air terminal size

Verify design by air flow per surface area

Reset demo

All modification uses generic parameter and type access

Changes are reflected by schedules and colour fill

2012 Autodesk
Pipe to Conduit Converter

Two hundred lines of code

My First Revit 2011 Add-in

Illustrates all major Revit 2011 API renovations

Revit API assembly split

Namespace reorganisation

Command registration manifest

External command Execute method and attributes

Transaction mode

Regeneration option

Task dialogues for user messages

Interactive filtered element selection

Redesigned element filtering

New element creation paradigm

Access to pipe and conduit sizes
2012 Autodesk
Cable Tray Fitting Creation and Layout

Inserting a cable tray is as easy as a conduit, cf. p2c

Inserting fittings requires exact alignment, i.e. proper orientation

2012 Autodesk
Modeless Loose Connector Navigator

Modeless navigation interacting with Idling event

Ensure that modeless dialogue remains on top of Revit

Filter for all MEP connectors in project

Combine all relevant classes and family instance categories

Check IsConnected property on each connector

Log results to file and display to user

Interact with Revit and navigate through results in modeless dialogue

2012 Autodesk
MEP Placeholder Sample

Placeholder ducts and pipes

CreatePlaceholders and ConvertPlaceholders commands

Duct and pipe insulation and lining

InsulateDuctwork command

Read and write access to MEP pipe settings and sizes

GetPipeSettings command

2012 Autodesk
Summary and Further Reading

2012 Autodesk
Materials

Blog posts

http://thebuildingcoder.typepad.com/mep

Hand-outs and sample code

CP4108_tammik_rme_api.pdf

CP4108_tammik_rme_api.zip

MEP placeholder sample MepPlaceholders.zip

HVAC and electrical MEP sample code AdnRme.zip

Modeless loose connector navigator loose_connectors_11.zip

Cable tray sample CableTray.zip

2012 Autodesk
Learning More

Revit Developer Center: DevTV and my first plugin introductions, SDK, samples, and API help

http://www.autodesk.com/developrevit

Product Online Help and Developer Guide

http://www.autodesk.com/revitapi-wikihelp

ADN Revit and Revit MEP API Webcasts, Trainings and Archives

http://www.autodesk.com/apitraining

http://www.adskconsulting.com/adn/cs/api_course_sched.php > Revit API

http://www.adskconsulting.com/adn/cs/api_course_webcast_archive.php > Revit API

Discussion Group

http://discussion.autodesk.com > Revit Architecture > Revit API

ADN AEC DevBlog and The Building Coder Revit API Blog

http://adndevblog.typepad.com/AEC

http://thebuildingcoder.typepad.com

ADN, The Autodesk Developer Network, and DevHelp Online for ADN members

http://www.autodesk.com/joinadn

http://adn.autodesk.com

Learning Autodesk Revit MEP 2012 video training

http://cad-notes.com/2011/12/learning-autodesk-revit-mep-2012-training-video-is-available
2012 Autodesk
Class Summary

Overview of the Revit MEP API

MEP API enhancements in Revit 2013

Working programmatically with Revit MEP models

Overview of available Revit MEP API samples

2012 Autodesk
Learning Objectives
So... are you now able to:

Use the Revit MEP 2013 API enhancements?

Analyze, create, manage and modify electrical, HVAC and plumbing
models, systems, and components programmatically?

Understand and reuse Revit SDK and ADN sample functionality?

Good luck and much success!

2012 Autodesk
Autodesk, AutoCAD* [*if/when mentioned in the pertinent material, followed by an alphabetical list of all other trademarks mentioned in the material] are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and/or other countries. All other brand names, product names, or trademarks belong to their respective holders. Autodesk reserves the right to alter product and
services offerings, and specifications and pricing at any time without notice, and is not responsible for typographical or graphical errors that may appear in this document. 2012 Autodesk, Inc. All rights reserved.
2012 Autodesk