Advanced Revit 2014 API Features and Samples

Jeremy Tammik – Autodesk

DV2010 This class focuses on some of the major new Autodesk Revit 2014 API features. We look at API
access to the project browser, dockable panels, copy and paste, command launching, the graphics pipeline, schedule
formatting, and additions to the view API including demonstration and discussion of sample code. We also provide an
overview of all the new Revit 2014 SDK samples. Note that prior .NET and Revit programming experience is required
and that this class is not suitable for beginners.

Learning  Objectives  
At the end of this class, you will be able to:
• Grasp the enhancements and new functionality provided by the expanded Revit 2014 API
• Know all the new Revit SDK samples and be able to reuse the sample code provided
• Make use of the new direct access to the Revit graphics pipeline to easily access and export geometry primitives
• Explore and reuse advanced Revit API sample code not found in the standard SDK samples

About  the  Speaker  

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 United States, 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, carpentry, and
loves mountains, oceans, sports, and especially climbing.
[email protected]  
Advanced Revit 2014 API Features and Samples

Overview    
We discuss a selection of advanced Revit 2014 API features and sample add-ins, including an overview of
all new Revit SDK samples. To see the screen snapshots illustrating the SDK samples in action, please
refer to the slide deck accompanying this documentation.

Table  of  Contents  

Overview  ..............................................................................................................................................................  2  
Table  of  Contents  ......................................................................................................................................................  2  

Revit  2014  API  News  .............................................................................................................................................  2  

Structural  Analysis  Software  Development  Toolkit  ...............................................................................................  3  

New  SDK  Samples  .................................................................................................................................................  4  

DisplacementElementAnimation  ...............................................................................................................................  4  
DockableDialogs  ........................................................................................................................................................  5  
DuplicateViews  ..........................................................................................................................................................  5  
ExtensibleStorageUtility  ............................................................................................................................................  5  
FreeFormElement  ......................................................................................................................................................  5  
PostCommandWorkflow  ...........................................................................................................................................  6  
ScheduleAutomaticFormatter  ...................................................................................................................................  6  
ScheduleToHTML  .......................................................................................................................................................  6  
SinePlotter  .................................................................................................................................................................  6  
Site  .............................................................................................................................................................................  7  
Units  ..........................................................................................................................................................................  8  
WinderStairs  ..............................................................................................................................................................  8  

MEP  Calculations  in  External  Services  ...................................................................................................................  8  

Access  to  the  Revit  Graphics  Rendering  Pipeline  ...................................................................................................  8  

Documentation  and  Materials  ..............................................................................................................................  9  

The  Building  Coder  ....................................................................................................................................................  9  
GitHub  Repositories  ..................................................................................................................................................  9  
Learning  More  ...........................................................................................................................................................  9  

Revit  2014  API  News  

1
A large amount of new functionality was provided in the Revit 2014 product update , and the Revit API
2
highlights and DevDays presentation reflect both the new product features and some add-in specific
aspects. Here is a list and brief summary of some of the main items:

1
http://thebuildingcoder.typepad.com/blog/2013/03/supporting-columns.html
2
http://thebuildingcoder.typepad.com/blog/2013/03/revit-2014-api-and-room-plan-view-boundary-polygon-
loops.html#2

2
Advanced Revit 2014 API Features and Samples

• Structural Analysis SDK

• Copy and paste API – within or between documents, including view specific elements
• Project browser API – commands, macros, selected elements
• Schedule API – formatting, read-write access to data items
• Command API – launch macros, add-in and built-in commands
• Displaced elements API – enables exploded views
• Join geometry API – create, remove and control concrete joins
• FreeForm element API – modification of imported solids
• Site API – editing of topography surface points and sub-regions
• Add-in API – mid-session loading and execution of add-ins
• Macro API – list, create, delete and execute macros and modules
• MEP calculations in external services
• Direct API access to rendering pipeline
The long requested API access to the project browser and selected elements; API commands and macros
are now enabled in the browser view. The copy and paste API supports copy within or between
documents including view-specific elements. As with most new product features, there is full API support
for the new non-rectangular crop regions. The Schedule API introduced in Revit 2013 is now expanded to
provide formatting control and read-write access to individual data items. The Command API enables
programmatic command launch including built-in Revit, external add-in and macro commands. The Add-in
API supports mid-session loading and execution. The displaced element API enables exploded views.
The Join geometry API can be used to create or remove a Boolean join and control join order. The
FreeForm element API enables modification of solid geometry imported from e.g. DWG or SAT. The Site
API enables editing of topography surface points and supports sub-regions. MEP calculations are now
implemented supporting the external services framework and can be replaced by add-ins. A number of
structural reinforcement and rebar enhancements were made. The document open, save and worksharing
API was enhanced. The Linked model API supports loading, unloading, path manipulation, link
identification and creation. Linked model interaction enables tag creation for linked rooms, linked element
selection, geometric reference conversion, etc. The API supports importing DXF markup, import and
linking of SAT and SketchUp. Export to NavisWorks is enabled via an add-in, and the API can now access
DWG, IFC and DGN layer, linetype, lineweight, font and pattern tables. The API now supports direct
access to the rendering output pipeline including all geometry and material properties. The Macro API
provides support for Python and Ruby development plus list, create, delete and execute modules, macros
and security settings.
For the full and gory details, please refer to the What's New section in the Revit 2014 API help file
3
RevitAPI.chm .
All of these areas are illustrated by new Revit SDK samples or sample code provided on The Building
Coder blog. We can therefore go through and discuss the additions to the Revit SDK while exploring
these areas at the same time.

Structural  Analysis  Software  Development  Toolkit  

4
The first item listed above is the Structural Analysis SDK . It lives in its own sub-folder of the Revit SDK
and consists of documentation, sample code and Visual Studio templates for two main components:
• Code checking framework
o Facilitate code checking workflows
o For both users and developers

3
http://thebuildingcoder.typepad.com/blog/2013/04/whats-new-in-the-revit-2014-api.html
4
http://thebuildingcoder.typepad.com/blog/2013/06/structural-analytical-code-checking-and-results-builder.html

3
Advanced Revit 2014 API Features and Samples

o Complete extensible add-in

o User interface, report generator, data storage
o Documentation, samples, Visual Studio templates
• Results builder framework
o Store and access results data in Revit
o High-level API for consumption, exchange, remote providers
Here is an overview of the sample applications provided with this toolkit:
• ExtensibleStorageUI and ExtensibleStorageDocumentation – exercise the ExtensibleStorage
framework user interface and reporting functionality.
• CodeCheckingConcreteExample – a concrete code checking application with step-by-step document.
• ConcreteCalculationsExample – concrete calculations component for all cases listed in the
calculation manual.
• SectionPropertiesExplorer – demonstrate use of the engineering component.
• StoringResults and QueryingResults – store and query structural analysis results BIM using the
results builder component.

New  SDK  Samples  

5
The following new Revit SDK samples were added in Revit 2014 :
• DisplacementElementAnimation
• DockableDialogs
• DuplicateViews
• ExtensibleStorageUtility
• FreeFormElement
• PostCommandWorkflow
• ScheduleAutomaticFormatter
• ScheduleToHTML
• SinePlotter
• Site
• Units
• WinderStairs
We will step through these one by one and simultaneously explore the underlying API enhancements.
Each of the samples discussed includes its own more detailed and in-depth description in its
corresponding readme file.

DisplacementElementAnimation  
The element displacement functionality is an important Revit 2014 product enhancement. From the API
point of view, a DisplacementElement can be used to make an element appear displaced from actual
location. The DisplacementPath creates an annotation line connecting the displaced element to its original
location. The DisplacementElementAnimation SDK sample drives it programmatically to create a visually
6
impressive animation .
• Programmatically drive element displacement
• Animated exploded view using Idling event
• Sort members into groups based on category and level

5
http://thebuildingcoder.typepad.com/blog/2013/07/revit-2014-obj-exporter-and-new-sdk-samples.html#3
6
http://thebuildingcoder.typepad.com/blog/2013/08/animation-and-the-displacementelement-class.html

4
Advanced Revit 2014 API Features and Samples

• Displace from actual position at command begin

• Animate group by group back to original position
• DisplacementElement and DisplacementPath
This is an external application, so it needs to be installed separately and defines its own ribbon panel.

DockableDialogs  
The Revit API has been steadily enhancing the possibilities for add-ins to integrate seamlessly into the
user interface. Now an add-in can also create it own modeless dockable Revit UI panels and populate
them with WPF controls. The dockable panel UI API framework is used by an external application and
driven through external events to enable a modeless dialogue design, as illustrated by the
DockableDialogs SDK sample. It is an external application, so it needs to be installed separately and
defines its own ribbon panel. The IDockablePaneProvider interface is called when the user brings the
7
pane into focus. The SDK sample is rather complex, and two simpler samples are provided on the blog .
8
The Revit Ruby Shell uses a dockable panel as well . The zero document behaviour in the initial release
was resolved by the Revit 2014 update release 2.

DuplicateViews  
One of the most powerful and most widely useable Revit 2014 API is enhancements is the new copy and
paste API. The DuplicateViews SDK sample uses this to copy drafting views and schedules to a new
document, including the drafting view contents. This is an external application, so it needs to be installed
separately and defines its own ribbon panel. Some of the many other possible examples of using the copy
9
and paste API include :
• Duplicating a view from one document to another
• Solving the non-unique unique id problem
• Managing materials in adsklib or template files
• Transferring groups between projects
• Copy family symbols to another project

ExtensibleStorageUtility  
The Revit 2014 API provides several minor yet important enhancements related to extensible storage:
• The Element.GetEntitySchemaGuids methods returns the schema GUIDs of all entities present on
the element
• The new ExtensibleStorageFilter is a quick filter that retrieves all elements with a given schema
GUID.
• The Schema GetField and ListFields methods now honour the access restricted by schema read
permission settings.
The ExtensibleStorageUtility SDK sample defines two external commands, Query and Delete, accessible
via RvtSamples > Element. They enable you to query whether storage for given schema exists in the
document, retrieve and delete elements.

FreeFormElement  
The new FreeFormElement functionality enables parametrisation of non-parametric imported geometry.
From the product point of view, you can import a solid model for AutoCAD or some other source, then
modify it by offsetting its planar to create a whole family of similar parts with different dimensions.

7
http://thebuildingcoder.typepad.com/blog/2013/05/a-simpler-dockable-panel-sample.html
8
http://thebuildingcoder.typepad.com/blog/2013/05/revitrubyshell-for-revit-2014.html
9
http://thebuildingcoder.typepad.com/blog/2013/05/copy-and-paste-api-applications-and-modeless-assertion.html

5
Advanced Revit 2014 API Features and Samples

The FreeFormElement SDK sample uses this functionality to create a new family representing a negative
of an existing selected non-parametric element. In the user interface of the project environment, you are
prompted to select the target solid element template and a closed loop of curves. These are used to
programmatically create a new generic model family. The code creates a FreeFormElement extrusion
from the selected curve loop and subtracts the target solid from it. The resulting family is loaded back into
the project and an instance is placed, aligned with the original curves.
This is an external application, so it needs to be installed separately and defines its own ribbon panel. It
also includes a sample project to run it in.
10
The Building Coder presents a simpler sample using the FreeFormElement to save a solid to a SAT file .

PostCommandWorkflow  
The Revit 2013 API already enabled an add-in to redefine an existing Revit command, but it was still not
possible to launch one programmatically. This long-standing wish is now fulfilled, and add-ins can finally
launch built-in Revit commands.
The PostCommandWorkflow SDK sample demonstrates making use of this to achieve a custom workflow
after command execution. It subscribes to the DocumentSaving event in order to modify the standard
Revit save behaviour based on the number of revision elements.
It implements a complex workflow with custom events, including a custom event type implementing the
IExternalEventHandler interface.
This is an external application, so it needs to be installed separately and defines its own ribbon panel.
The Building Coder explores using this to launch your own add-in commands as well, and how to
11
determine the identifiers required to do so from the journal file .

ScheduleAutomaticFormatter  
Revit 2013 provided significant new functionality to manipulate schedules. This was continued in the Revit
2014 API, which enables access to individual cells and formatting.
The ScheduleAutomaticFormatter shows how this can be used to colour-format alternating columns of a
schedule table. It formats the columns of the active schedule in alternating colors. The formatting data is
also stored in extensible storage, and the dynamic model update mechanism DMU is used to
automatically reformat the columns when required. It makes use of the TableCellStyle and
TableCellStyleOverrideOptions classes.

ScheduleToHTML  
The related ScheduleToHTML SDK sample exports and displays a schedule in formatted HTML. Do do
so, it handles the header, body, background color, bold, italic, underline, horizontal alignment, and merged
cells properties and exercises the ViewSchedule, TableData, TableSectionData, TableCellStyle and
TableMergedCell classes.

SinePlotter  
The SinePlotter SDK sample illustrates the interaction with a couple of ribbon widgets:

10
http://thebuildingcoder.typepad.com/blog/2013/09/saving-a-solid-to-a-sat-file-implementation.html
11
http://thebuildingcoder.typepad.com/blog/2013/10/programmatic-custom-add-in-external-command-launch.html

6
Advanced Revit 2014 API Features and Samples

It creates a sine curve representation using an array of prism family instances. You can choose between
different prism family types, including Cylinder, Rectangular, Regular Polygon and Isotriangle. The
modifiable settings include the curve period, curve cycles, curve amplitude and number of partitions. The
sample can be run in the accompanying sample model CurvePlottingSample.rvt, and you hit the "Enter"
key for the text box edits to be accepted.

Site  
Revit 2014 includes new functionality related to sites, regions and building pads. From the API point of
view, this is reflected in the following new functionality:
• Reading, editing and validating points for a TopographySurface
• SiteSubRegion
• BuildingPad

TopographySurface  
The TopographySurface class provides new methods ReadPoints and FindPoints to retrieve all its points
or filter and return only the ones within a bounding box. The method ContainsPoint tests whether an input
point is found in the points stored. GetBoundaryPoints and IsBoundaryPoint identify points that are a part
of the surface boundary.
The validation methods include IsValidRegion to identify whether the points can construct a valid
topography surface region and ArePointsDistinct to check for and avoid problems before calling
AddPoints.
Editing the points in a TopographySurface now requires establishment of an edit scope, represented by
the TopographyEditScope class. Start and end of a TopographyEditScope also start and end a
transaction group. After the TopographyEditScope is started, an application can start transactions and edit
the topography surface. Individual transactions the application creates inside TopographyEditScope will
not appear in the undo menu. All transactions committed during the edit mode are merged at the end.
The AddPoints method operates now cannot be called outside of an edit scope and no longer regenerates
the document. The new methods DeletePoints, MovePoint, MovePoints, ChangePointElevation and
ChangePointsElevation modify and delete existing points.

SiteSubRegion  
The SiteSubRegion class represents a proxy class exposing the interfaces needed to access details of a
subregion. In the Revit database, both topography surface and subregion elements are represented by
the same TopographySurface object. The SiteSubRegion class provides the methods and properties
Create, IsValidBoundary, GetBoundary, SetBoundary, TopographySurface and HostId.

BuildingPad  
The BuildingPad class represents a building pad element in Revit. It inherits from CeilingAndFloor and
exposes the following additional functionality:
• Create – Creates a new BuildingPad given a boundary, type and level.
• GetBoundary – Returns the sketched boundary curves.
• SetBoundary – Assigns a new boundary to the BuildingPad.
• HostId – The element id of the topography surface hosting this BuildingPad.
The building pad type is represented by the BuildingPadType class, derived from HostObjAttributes, thus
providing access to the CompoundStructure of the type, among other things. The BuildingPadType
CreateDefault method creates a new default building pad type instance.

7
Advanced Revit 2014 API Features and Samples

Site  SDK  Sample  

The Site SDK sample enables editing a topography surface and site sub-region to create a circular
retaining pond topography family at a user specified location, move the sub-region and its points, raise
lower, normalise and delete the sub-region terrain, exercising the TopographySurface, SiteSubRegion and
TopographyEditScope classes.

Units  
The Unit API has been completely renovated in Revit 2014. The Units SDK sample demonstrates the new
usage. It lists the units in the current project, displays format information and the format modification
options for each unit type. The Building Coder provides samples diving deeper into the topic, exploring
12
how to generate unit abbreviations and map display unit types to unit types .

WinderStairs  
Revit 2013 introduced a completely new stair element providing much more power and flexibility. Revit
2014 expands on this, adding support for winder stairs and other functionality. The WinderStairs SDK
sample demonstrates making use of this functionality to programmatically create sketch-based winder
stairs, supporting L and U-winder layout algorithms and using the dynamic model update framework DMU
for automatic regeneration. To run the sample, select some existing model lines or walls and specify the
run numbers and width, e.g. in the sample model provided, WinderStairs.rvt.

MEP  Calculations  in  External  Services  

The external services framework was introduced in Revit 2013, but not used in that version.
Revit MEP 2014 makes use of the external services itself. The service implementations live in the
MEPCalculation sub-folder of 'C:\Program Files\Autodesk\Revit 2014\AddIns'.
13
A User MEP Calculation example implementation is presented on The Building Coder.

Access  to  the  Revit  Graphics  Rendering  Pipeline  

Last and definitely not least: one of the most important enhancements in the Revit 2014 API is the new
custom exporter framework providing direct API access to the graphics output pipeline, including
geometry and material properties. To retrieve the graphics output for the current view, and add-in can
implement a custom exporter class implementing the IExportContext interface, create an instance of it,
14
passing in the desired document and context and call its Export method . The custom exporter has
15
access to texture bitmaps and their UV coordinates . The Building Coder provides one full-fledged
custom exporter for retrieving and caching all possible data for debugging and exploration purposes, an
exporter by Artur Brzegowy of Act-3D B.V. supporting the Collada model visualisation format, and an
implementation for custom ADN JSON output.

12
http://thebuildingcoder.typepad.com/blog/2013/11/mapping-display-unit-type-to-unit-types.html
13
http://thebuildingcoder.typepad.com/blog/2013/07/user-mep-calculation-sample.html
14
http://thebuildingcoder.typepad.com/blog/2013/07/graphics-pipeline-custom-exporter.html
15
http://thebuildingcoder.typepad.com/blog/2013/07/texture-bitmap-and-uv-coordinates.html

8
Advanced Revit 2014 API Features and Samples

Documentation  and  Materials  

The  Building  Coder  
Most of the content of this document has been published on The Building Coder Revit API blog
thebuildingcoder.typepad.com. A summary of all the links listed in the footnotes above is provided by the
16
Advanced Revit 2014 API Features and Samples overview .

GitHub  Repositories  
The source code for all applications discussed above is available either from the Revit SDK or my GitHub
repositories at https://github.com/jeremytammik.

Learning  More  
• Revit Developer Centre: DevTV and My First Plugin Introductions, SDK, API Help, Samples
http://www.autodesk.com/developrevit
• Developer Guide and Online Help
http://www.autodesk.com/revitapi-wikihelp
• Revit API Trainings, Webcasts and Archives
http://www.autodesk.com/apitraining > Revit API
• Discussion Group
http://discussion.autodesk.com > Revit Architecture > Revit API
• API Training Classes
http://www.autodesk.com/apitraining
• ADN AEC DevBlog
http://adndevblog.typepad.com/aec
• The Building Coder, Jeremy Tammik's Revit API Blog
http://thebuildingcoder.typepad.com
• ADN, The Autodesk Developer Network
http://www.autodesk.com/joinadn and http://www.autodesk.com/adnopen
• DevHelp Online for ADN members
http://adn.autodesk.com

16
http://thebuildingcoder.typepad.com/blog/about-the-author.html#5.22