REVIT API

FILTERED ELEMENT COLLECTOR

+ FILTERS

2022 www.erikfrits.com Made by Erik Frits

 PAGE 2 MADE BY ERIK FRITS

Welcome to this Guide Table of Content

This is the most comprehensive guide about FilteredElementCollector
It’s something I wish I had when I started learning Revit API.
So Enjoy, it should make it much easier for you! 3 FilteredElementCollector
4 FilteredElementCollector Anatomy
5 How to work with FEC?
Who am I?
My Name is Erik Frits. 6 Look inside your Elements!
7 Imports, Variables, Functions
I am BIM Specialist focusing on
Software Development and Automation. 8 Simple Examples
9 Getting Annotations and Tags
I am creator of EF-Tools extension and
I teach people RevitAPI + python 10 Getting Views and Sheets
on my YouTube channel. 11 Python filtering vs RevitAPI Filters
www.youtube.com/c/ErikFrits
12 RevitAPI Filters: Introduction
13 RevitAPI Filters: Samples
www.linkedin.com/in/erik-frits/
14 ElementParameterFilter
www.youtube.com/c/ErikFrits
15 ElementParameterFilter: Text
16 ElementParameterFilter: Numeric
I would appreciate if you become my Supporter
17 ElementParameterFilter: ElementId
To see more stuff like this.
18 RevitAPI Logical Filters
PATREON : www.patreon.com/ErikFrits 19 Get MEP Elements
KO-FI : www.ko-fi.com/ErikFrits 20 Get MEP Elements with Filters

IT’S ABOUT TIME TO LEARN ABOUT

FilteredElementCollector
 PAGE 3

FilteredElementCollector
This class is used to search, filter and iterate through a set of elements.
There are many methods available to simplify this process, but we can
also dive deeper and create our own custom filters, which we will look
into later in this Guide.

If you’re new to RevitAPI and want to start writing your own scripts,
you’ll need to learn how to use FilteredElementCollector. It’s a class
that is used nearly in every script that you are going to write .

You can learn more about available methods and Filters by looking
inside of revitapidocs.com. That’s an online RevtiAPI documentation,
which we need to refference from time to time.

How to create a FEC?

Before we start filtering our selection with the
collector we need to create it. If you look at the
screenshot on the left you can see that it takes
Document as an argument, which refers to your
Revit Project. we will have a variable called doc.

This Guide is intended to help you understand the

logic of using FilteredElementCollector class.

There won’t be examples for every single case-sce-

nario, but there will be plenty so you can get a feel
for how it works and apply it for your scripts.
 PAGE 4 MADE BY ERIK FRITS

FilteredElementCollector Anatomy
This is a typical use of FilteredElementCollector()
Let’s break it down to pieces.

Optional*

Provide View.Id as 2nd arg

to select visible elements
in View

A B C D
Create a collector Filter by Category/Class Filter to Types/Instances To Elements/ElementIds
To create a collector, first we need Secondly, we need to filter by By now, we are getting both Lastly, we just need to convert
to provide a Document from category or class. instances and types. this collector into a list of usable
where we want to get elements Some Classes have the same We can use FEC methods to objects.
as an argument. category, and some elements filter down selection to
are not possible to get with instances or Types. In most cases I use
In addition, we can also provide OfClass method. .ToElements() ,but sometimes
the View.Id as an optional These methods do not take any you might prefer to use
second argument if you want to .OfCategory(BuiltInCategory) arguments. .ElementIds()
limit your selection to visible .OfClass(type)
elements in the given view.

This is a common way of getting your Elements from a project. We define a Category, Filter only to Instances and returning a list of Elements.
 PAGE 5

How to work with FEC?

This line below looks very long and complicated if you
see it for the first time. But it is surprisingly easy to
modify it to get other elements.

Right now it returns a list of Floors Instances.

If we want to get Floor Types, we just need to replace

.WhereElementIsNotElementType() -> WhereElementIsElementType()

If we want to get Door Instance, we just need to replace

BuiltInCategory.OST_Floors -> BuiltInCategory.OST_Doors
Image of FEC Methods with
description If we want to get ElementIds, we just need to replace
.ToElements() -> .ToElementIds()
We can add more filters if we
If we want to get visible Elements from a specific view, want to be more specific, or we
we just need to add View.Id as a second argument. can use even less filters.
.FilteredElementCollector(doc) -> .FilteredElementCollector(doc, view.Id)

For Beginners I would

Now it is not that complicated! is it? recommend keeping it simple
and filter elements using
conditional statements with for
loops or list comprehensions.
There will be examples.

Modify here to Change Category Here. Remove Not if Change here if you
Select from View RevitAPI Autocomplete you want Types want ElementIds.
will show you all the
BuiltInCategories
 PAGE 6 MADE BY ERIK FRITS

Look inside your Elements!

If you’re unsure of the internal name of a parameter or what
values can be retrieved from an element, we can look inside!
There is a free open-source plugin called ‹‹Revit LookUp››

It is super helpful to quickly get an overview of what’s going on

inside your elements.

I use it every single time I create a tool. It gives you so much

information and sometimes can even save you couple hours
when you discover a method that helps you a lot.

When you look inside your elements with RevitLookup, you can
see a menu with all the properties and methods available for the
element

We can explore even further if property or method is bold.

e.g. Clicking on parameters will open a menu with all available
parameters, where we can look at methods and properties of
each parameter.

Then we can look even further into Definition of a specific pa-

rameter to see its Id and if it is a built-in parameter or not.

Always explore the Elements you are working with!

Download: https://github.com/jeremytammik/RevitLookup
 PAGE 7

Imports, Variables, Functions

Before we dive into all the examples, let’s make sure that we are on
the same page. I use Revit 2021 and you can see everything we will
need to work with FilteredElementCollector in this guide.

IMPORT & VARIABLES CONVERT UNITS

These are the simpliest imports and variables that I tried to avoid using anything extra, but since I work in
we need in our scripts. We will have more imports cm units and Revit uses imperial units internally I need
for Structural and MEP elements. to convert units.
And I am sure many of you will find it useful!
Notice that we are importing List from .NET library
and it’s different to python list() that is often We could simply divide values by 30,48 but this might
required for RevitAPI methods. cause minor inconsistencies with Revit rounding and
sometimes causes rounding error in calculations. So I
would suggest you use this snippet for convertion.
 PAGE 8 MADE BY ERIK FRITS

Simple Examples
To prove you that it really is that simple, Look at the snippet on the
right with different examples of getting Elements.

You just need to replace very little to get another

Category or Class of Elements.

Try opening RevitPythonShell or pyRevit script and

Practice getting different elements yourself!
Experiment with it and print your results to compare.

If you use python node in Dynamo, You will need

to create more refferences and imports.
 PAGE 9

Getting Annotations and Tags

If you want to get 2D Annotations and tags, you
can use BuiltInCategory or Class of element as
well. It’s the same principle as we did for 3D Ele-
ments.

You just need to know what the right category

or class is and then you will be able to easily get
them.

We can use Revit Lookup to have a look inside to

find the right name. You don’t need to know it by
heart, you just need to know where to look.
 PAGE 10 MADE BY ERIK FRITS

Getting Views and Sheets

Getting Views and Sheets is very
straight-forward. But there is a trick if you
want to get more specific views like
FloorPlan or Sections, then we need to cre-
ate more filters.

Filters are not always necessary when you

work with RevitAPI, especially if you are just
starting.

I would strongly recommend to get all

elements by category first and then filter
with python conditional statements or
list comprehensions.

Check 2 snippets below and compare the

code. They are both getting the same
results, but I find List Comprehensions
more readable.

It’s up to you how you prefer to code it.

 PAGE 11

Python filtering vs RevitAPI Filters

I will explain Filters in a moment.

But firstly, let’s compare RevitAPI
Python Filters with just getting all elements RevitAPI
Filtering with python conditional statements. Filters
Both snippets below are getting
50cm high walls from the project.

Which one do you prefer?

 PAGE 12 MADE BY ERIK FRITS

RevitAPI Filters: Introduction

Finally, it’s time to explore RevitAPI FIlters! Let’s look at ElementMulticategoryFilter.
It’s fairly simple and you can see its
If you scroll through Autodesk.Revit.DB in constructor methods on the right.
docs, you will notice quite a lot of different
First of all we need to create a list of built-in
Filters. We often need to refference docs to categories: List[BuiltInCategory]()
see how to work with different filters.

Once you have this list of categories

you just need to pass it to
ElementMulticategoryFilter(cat_list)
REVIT API DOCS And then you can use this filter with
FILTER SEARCH FilteredElementCollector by using
.WherePasses() method

On the other hand, we could just get all

elements seperately and then combine
them into a single list.

There are often easier ways to get your

elements, even if it is less efficient.

If you are a beginner programmer, then just

focus on getting your elements with what-
ever works the best for you.
I am going to show you more examples that
might encourage you to use RevitAPI Filters.
 PAGE 13

RevitAPI Filters: More Samples

ElementLevelFilter
This filter is used to match elements by
their associated level. We just need to
provide Level.Id and filter is ready.

You can combine it with other

Filters or FEC methods to filter down
even more.

ElementIsCurveDrivenFilter
This filter is used to match elements
which are curve driven.
The term «curve driven» indicates that
the element’s Location property is a
LocationCurve.

Examples:
- Walls
- Beams
- Curve elements...

ElementStrucuralTypeFilter:
This filter is used to find elements
matching a structural type.

RevitAPI Autocomplete will show

you all available options for
StructuralType.
 PAGE 14 MADE BY ERIK FRITS

ElementParameterFilter

Introduction Parameter Value Parameter

That’s a very powerful filter but it also a little Value just needs to match We need ElementId of our
harder to use than previous Filters. Parameter’s StorageType. parameter.
But don’t worry, we are getting there! Also depending on Evaluator Use Revit Lookup to look
you need to provide exact or inside of your element
Let’s break down all the step we need to do to partial match. parameters and you can see
create an ElementParameterFilter. Internal name in Definition.

This is similar to defining a Rule

in Revit Filters.

Evaluator
Evaluator is just a class representing
equal, less, more, etc...
You can see them on the right.

There are different classes for String and

Parameter Evaluator Numerical types. Overall it’s the same
Value as choosing evaluator in regular Revit
Filters.
It’s the same in RevitAPI
We need to prepare: P.S. ElementId and Bool Parmaeters also
- Parameter use Numerical evaluators.
- Parameter Value
- Value Evaluator

Then we need to create a Rule similary to the

screenshot above, but with the code.
We might also need to provide extra argu- Rule
ments depending on the StorageType such as: We Create rules to combine Parameter, Parameter
CaseSensetive or Tolerance. Value, Evaluator and some extra parameters like
Then we can easily create a filter from this caseSensitive or tollerance.
Rule.
I have avoided this Filter for a very long, You will understand it
But you don’t have to with this Guide! more after seeing more
examples in the next
pages.
 PAGE 15

ElementParameterFilter: Text
Get Elements By Type/Family Name
Let’s create a Filter to get elements
by Type or Family Name

Parameter Practice makes it perfect

I prepared 2 parameters for you to You need to practice getting different parameter. Create a few filters in Revit UI and try
choose from: to get the same elements with Revit API. It might be easier to create rules with python if
ALL_MODEL_TYPE_NAME you see it first in Revit UI.
ALL_MODEL_FAMILY_NAME

In my case, I want to filter all elements

with the type name ‘Ziegeldach 360‘,
so I will use parameter for Type Name.

Create a Rule
Creating a rule is not hard as it seems.
FilterStringRule takes 4 arguments and you
can see a snippet on the right.

You’ll find that once you get the hang of it, it’s
super easy to make rules in Revit. You just need
to practice a few times, and then it will become
natural to use.

Create Filter
Creating filter is simple, just provide a rule that
you want to apply and it’s done.

Now we just need to pass this filter with

.WherePasses method and it will filter
according to the values that we gave it.
 PAGE 16 MADE BY ERIK FRITS

ElementParameterFilter: Numeric
Get Walls with Height of 50cm

Let’s use the same filter but this time we

will use a Numeric parameter.

This example will show you how to get all

walls in the project with a height of 50cm.

Compraing to the previous example, this

time we need to use
FilterDoubleRule instead of a
FilterStringRule and we need to use an
evaluator class that suits Numeric type.

I chose FilterNumericEqual to get walls

with the exact height of 50cm.
But you can get walls with more or less
than 50c, just change evaluator to:
FilterNumericGreater() or
FilterNumericLess()
 PAGE 17

ElementParameterFilter: ElementId
Get Elements of the same category

By now you should understand how to

create ElementFilterParameter, but let’s
have one more example with
FilterElementIdRule() Parameter.

As I have mentioned earlier it uses the

same evaluators as Numeric type be-
cause ElementId is a number afterall.

This time we need to use

FilterElementIdRule and evaluator of
FilterNumericEquals()

You can use this snippet to get all

elements of the same category as the
provided element. Could be useful to get
same category elements in view.
 PAGE 18 MADE BY ERIK FRITS

RevitAPI Logical Filters

Logical filters are used to combine multiple filters together. LogicalOrFilter
There are 2 methods to create them. This filter is good when you have multiple filters and
We can provide 2 filters as seperate arguments, or we need to create you want at least one of them to evaluate to True.
a List<>(ElementFilter) and then provide it as a single argument
For example, I used LogicalOrFilter in my Super Select
tool in EF-Tools.
I took my selection, and made a loop to create a filter
for each element to get elements of the same
Category and then I combined all these filters.

So if I would select 10 different elements, it would

create 10 filters in a loop and combine them all in a
single LogicalOrFilter.

LogicalAndFilter
Let’s say we want to use 2 filters
and both of them should
evaluate to True.

I want to create a filter to get all

walls with a word ‘wood’ in
Type name and a thickness of
greater than 10cm.

FILTER_1:
Get elements that contain a
word ‘wood’ in Type Name and
it’s not case sensetive.

FILTER_2:
Get all elements that have a
thickness of Greater than 10cm.

LogicalAndFilter:
Since we only have 2 filters, we
can just pass them
as 2 arguments.
 PAGE 19

Get MEP Elements

By now you know the principles and you can apply it
to elements from any discipline
- Architectural
- Structural
- MEP

Pay attention that if you use .OfClass() you might

need to import elements from other Disciplines
They are not in Revit.DB module but in:
Revit.DB.Mechanical,
Revit.DB.Electrical,
Revit.DB.Plumbing

The same principe applies for Structural elements.

Revit.DB.Structure
 PAGE 20 MADE BY ERIK FRITS

Get MEP Elements with Filters

Here is the final example to get your MEP elements
with ElementParameterFilter.
It’s the same workflow as I showed in previous pages.
We choose parameter, value and evaluator to create our
Rule and turn it into a Filter to use with
.WherePasses method of FEC.

Snippet on the left will get Elements

based on their System Name.

And Snippet below will get elements with

Pipe Diameter of 10cm within 0.1cm tolle-
rance.
 PAGE 21

Special Elements
Finally, there are some elements that we can’t get with
FilteredElementCollector, because they have their own
special classes to get them.
Here are a few examples below.
Unfortunately I could not remember more,
so if you stuble on a category of elements that
you can’t get even after reading this guide,
Let me know.
It might contribute to the second edition of this guide.
 THANK YOU
You made it to the end!

I hope I managed to explain

FilteredElementCollector well
enough for you to use.

What’s Next?

Share With Others Connect on Social Media Feedback

I would appreciate if you You can follow me on: I would appreciate if you
spread the word on social leave some feedback
media about this guide so it www.linkedin.com/in/erik-frits/ about this Guide!
can reach even more people. www.youtube.com/c/ErikFrits [email protected]