Transcript About the Presenter

Image courtesy of Hobart, Yañez, Ramos, Maguey, and Martínez
Exactly What You Want and Faster: Autodesk
Revit 2011 Programming Optimization
Jeremy Tammik
Principal Developer Consultant
Autodesk
Class Objective

You learn

New Revit 2011 API filtering and iteration techniques
 Benchmarks, performance and implementation considerations
 Aspects of regeneration and auto-join

We do not discuss and assume knowledge of

How to program in .NET
 The basics of the Revit API
 Revit product usage
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 and carpentry, loves mountains,
oceans, sports, and especially climbing.
Autodesk Developer Network

Access to almost all Autodesk software and SDK’s





Includes early access to beta software
Members-only website with thousands of technical articles
Unlimited technical support
Product direction through conferences
Marketing benefits

Exposure on autodesk.com
 Promotional opportunities

One to three free API training classes

Based on user level
www.autodesk.com/joinadn
Agenda









Filtered element collector overview
Filter types: logical, quick and slow
Filtering for elements
Post-processing using LINQ or explicit coding
Iterating over the results
Regeneration and Auto-Join
Benchmarking
Sample code with minimal error checking
Learning more
Sample Code

Minimal error checking


Add checks in your own code
Benchmarking uses Stopwatch

Simple timing utility System.Diagnostics.Stopwatch
 Built using low-level API calls
 Uses high-resolution performance counter instead of
standard PC clock assuming hardware and OS support
Filtered Element Collector Overview





Filtering moved to native side
Framework eliminates marshaling overhead
Removes much of the per-element access
Used internally by Revit itself for certain UI and DB operations
Performance improved there as well
Revit 2010 Element Iteration





Iterating elements was limiting and slower
Internal implementation details caused each access to marshal
between native/managed
Typical iterations were from Document.get_Elements API
Some filtering was available, but not as efficient
Compare old (simulated!) versus new performance
Revir 2010 versus 2011 Comparison
Example
2010 time in
milliseconds
2011 time in
milliseconds
Performance Gain
Filter for each API type
4828
618
7.8x
Filter all elements of ElementType
7
5
1.4x
Filter elements of Category
2588
789
3.2x
Filter elements by Parameter filter
49
20
2.4x
Filter elements of StructuralType
86
18
4.7x
Filter elements of StructuralUsage
210
43
4.8x
Filter elements of Structural MaterialTypes
116
16
7.2x
Filter Walls of Structural WallUsages
70
13
5.4x
Filter Enclosures and Tags
112
20
5.6x
Filter Curve-Driven Elements
53
3
17.7x
Filter elements of Design Options
51
35
1.5x
Filter elements on Levels
74
21
3.5x
Test results from internal qa engineer
Controlled cases with large data sets, programmatically created, not real-world
Using Filtered Element Collectors

1. Filtering is the base step – first decide what you want






2. Choose how to access results





source can be the model, a given set, or within a view only
easily combine multiple criteria
shortcuts for quick and common criteria
combine with other collectors through Intersection and Union
exclusions
Iterator for elements or element ids
Element set or element id set
IEnumerable and foreach or LINQ
get first element that matches (Element or ElementId)
3. Access and process elements

optionally use LINQ
FilteredElementCollector Class



Search, filter and iterate through a set of elements
Assign conditions to filter the returned elements
Requires at least one condition be set



Exception is thrown otherwise
Supports the IEnumerable interface
Tips

ElementFilters and shortcut methods offered by this class process
elements in native code before their managed wrappers are
generated. For best performance, use as many native filters as
possible before processing results
 Slow filters are still faster than post-processing data, because they still
expand and analyse data on native side
 Debugging weirdness: IEnumerable cannot be inspected, because real
data is on native side, so list does not contain any data
Filter Types

Logical Filters


Boolean combinations of other filters: And, Or
Quick filters

Use internal element records to determine passing state
 Find elements which have not been expanded into internal memory yet
 Examples: element class, category, bounding box
 Shortcuts available

Slow filters





Requires information not included in element record
Must load and expand element data to determine passing state
Examples: FamilyInstanceFilter, AreaFilter
No shortcuts available
Still faster than LINQ
Efficiency Guidelines





Filter as many quick aspects as possible
Filtering slow aspects is faster than post-processing
After using built-in filtering techniques, consider LINQ to
narrow down further
Tip: Use the FilteredElementCollector shortcut methods –
they all create a quick filter
Examples: OfClass, OfCategoryId
Logical Filters
Filter Name
LogicalAndFilter
Passing Criteria
Where elements must pass two or
more filters
Shortcut Methods
WherePasses adds one
additional filter
IntersectWith joins two sets
of independent filters
LogicalOrFilter
Where elements must pass at least
one of two or more filters
UnionWith joins two sets of
independent filters
Quick Filters
Name
Passing Criteria
Shortcut Methods
ElementCategoryFilter
Elements matching the input category id
OfCategoryId
ElementClassFilter
Elements matching the input runtime class
OfClass
ElementIsElementTypeFilter
Elements which are "Element types" (symbols)
WhereElementIsElementType
WhereElementIsNotElementType
ElementOwnerViewFilter
Elements which are view-specific
OwnedByView
WhereElementIsViewIndependent
ElementDesignOptionFilter
Elements in a particular design option
ContainedInDesignOption
ElementIsCurveDrivenFilter
Elements which are curve driven
WhereElementIsCurveDriven
ElementStructuralTypeFilter
Elements matching the given structural type
none
FamilySymbolFilter
Symbols of a particular family
none
ExclusionFilter
All elements except the given element ids
Excluding
BoundingBoxIntersectsFilter
Elements with bounding box intersecting given
outline
none
BoundingBoxIsInsideFilter
Elements with bounding box inside given outline
none
BoundingBoxContainsPointFilter
Elements with bounding box containing given
point
none
Slow Filters
Name
Passing Criteria
Shortcut
Methods
FamilyInstanceFilter
Instances of a particular family symbol
none
ElementLevelFilter
Elements associated to a given level id
none
ElementParameterFilter
Parameter existence, value, range, and string matching
none
PrimaryDesignOptionMemberFilter
Elements owned by any primary design option.
none
StructuralInstanceUsageFilter
Structural usage parameter for FamilyInstances
none
StructuralWallUsageFilter
Structural usage parameter for Walls
none
StructuralMaterialTypeFilter
Material type applied to FamilyInstances
none
RoomFilter
Finds rooms
none
SpaceFilter
Finds spaces
none
AreaFilter
Finds areas
none
RoomTagFilter
Finds room tags
none
SpaceTagFilter
Finds space tags
none
AreaTagFilter
Finds area tags
none
CurveElementFilter
Finds specific curve element types (model, symbolic, detail, etc.) none
Variants, Tips and Tricks

Select the correct collector constructor

A predefined subset of elements to search
 Only care about elements in a specific view




Use the filters in an inverted way
Use multiple filters to hone-in on something
Use the filters in complex combinations
Ordering may play a role

However, Revit automatically executes quick filters before slow ones
Filter Examples

Select all real structural elements







Visible elements intersecting a selected element


StructuralMaterialType.Steel
Interested in many types, e.g. brace, column, girder
Smaller number of uninteresting type, so use inverted filter
StructuralInstanceUsage NOT Automatic, Other, Undefined, or Wall
Create one single list of the five filters
Use a logical and filter to combine all five
Pick object, determine its bounding box for the active view, quick
bounding box filter, instantiate a collector for the active view, exclude the
picked element itself and the active view, report result
You can hopefully imagine the flexibilty this framework provides!
LINQ


.NET Framework Language Integrated Query
Includes set and transform operations
http://msdn.microsoft.com/en-us/netframework/aa904594.aspx

1. Further filter information using a query


2. Fast filter for non-native classes


find material of a given name; bic category is an id, no cast needed,
material defined by string; switch models to simple house
there is no native mullion class to look for; find family instances, then
filter for mullions; linq is a handy way to find them; OfType<> is fast
3. Using LINQ with other feature support:
create an XML family and instance usage report

use the Xml.Linq namespace for building xml file; for each family get
all symbols, for each symbol all instances, and report to XML
Don't Overuse ToElements

No need to explicitly create a list
FilteredElementCollector collector
= new FilteredElementCollector( doc );
// add filter criteria ...
ICollection<Element> ilist
= collector.ToElements();
foreach( Element e in ilist )
{
}

The collector itself is enumerable
foreach( Element e in collector )
{
}

Even worse, force enumeration and allocate memory for copies
List<Element> list
= collector.ToElements();
ElementParameterFilter







A unique filter designed for use with parameters
Requires provider, evaluator, values and rule
This is a slow filter, and may still be quicker than other types of
filters, depending on the circumstances
Definitely faster than post-processing results in managed code
Tip: use Revit Lookup to find the built-in parameter API name
for the desired parameter
Sample 1 of different parameter filters from internal test code
Sample 2 compares Level filter vs. parameter filter vs. LINQ

10 vs. 22 vs. 35 ms to extract 52 family instances on a given level
Materials

Handout


Presentation


AU10_CP234-2_Revit_2011_API_Optimization.docx
AU10_CP234-2_Revit_2011_API_Optimization.pptx
Sample code and models

AU10_CP234-2_Revit_2011_API_Optimization.zip
Learning More

Online Help, Developer's Guide and SDK Samples
 Revit Developer Center
http://www.autodesk.com/developrevit

DevTV Introduction to Revit Programming
 Webcasts and Trainings on Revit Programming and News
http://www.adskconsulting.com/adn/cs/api_course_sched.php > Revit API

Discussion Group
http://discussion.autodesk.com > Revit Architecture > Revit API

API Training Classes
http://www.autodesk.com/apitraining

The Building Coder, Jeremy Tammik's Revit API Blog
http://thebuildingcoder.typepad.com

ADN, The Autodesk Developer Network
http://www.autodesk.com/joinadn

DevHelp Online for ADN members
http://adn.autodesk.com
Autodesk [and other] 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. © 2010 Autodesk, Inc. All rights reserved.