Today I am returning back home from the very successful Revit API DevCamp in Moscow.
We received very good feedback from the participating developers who were so excited to learn about Revit programming that they ignored the hot environment, the unbearable sound of the false fire alarm and crazy running down the exterior staircase and back up again to the Autodesk offices on the 17th floor.
Here is Артур Кураков (Artur Kurakov) teaching one of the Revit API beginner sessions:
I presented in three sessions, on the Revit 2014 API, my 2D round-trip cloud-based Revit model editor, and, together with my colleague Steven Campbell, Revit Content Project Manager and our resident Revit family expert, on the Key Concepts of the Family Editor.
Steve demonstrates the basics and some advanced aspects of the manual creation of a Revit family, key concepts that you as a Revit add-in developer absolutely must be aware of.
I had the honour and pleasure of helping out by implementing some sample add-in commands that I am rather happy with, showing how to drive families and their instances programmatically in the Revit project environment. We'll get to those in a moment.
Let's start out with Steve's presentations:
Here are the two class descriptions, to define the context:
Mastering Revit family creation is a key to the success when using Revit. The same is true for Revit programmers. The use of Family API is largely analogous to the UI. Creating a family without fully understanding how Revit families work may lead to a bumpy road later on with your tasks. Knowing how much you can get through proper use of families opens infinite possibilities. This session offers an effective opportunity to learn directly from the family content expert, covering the following topics:
This is the continuation of the basic class on the key concepts of the family editor, presenting the following topics:
To give you a rough idea of the presentation contents, here is quick run-down of the slide deck bullet points:
What is a family?
A family is a group of elements with a common set of properties, called parameters, constraints, and a related graphical representations.
System vs. Standalone vs. In Place
Typically assemblies that are constructed on the construction site
Wall, Floors, Roofs, Ceiling, with some exceptions...
They only exist in a project or template file.
Standalone or "Loadable" Families:
Typically are manufactured pieces that are delivered to the construction site ready to install. They are intended to be used across many projects. Example: Windows, Doors, Light Fixtures, etc…
They are individual .rfa files.
In Place Families:
Project unique, built on site items that is stored only in the project.
So what is the best, most reliable way to build a family?
Build with the Bone, Muscle and Skin method.
Highest level of constraint is a labeled dimension attached to a reference plane.
The Bones, Muscle and Skin method describes the family as:
Bones = Reference Planes & Reference Lines
Muscle = Dimension, Label Parameters, Automatic Sketch Dimensions
Skin = Solids/Voids and Symbolic Linework
Blog Post by Steve Stafford: The Family Editor: Bones, Muscle & Skin
A work plane is a virtual 2-dimensional surface.
A work plane is used in the following ways:
Reference planes are the bones of a family
They have the added capability of defining the origin in a family, dimensioning to a family in a project, control snapping behavior and provide the availability of instance based shape handles.
Reference Lines are 3D lines with a start and end point that contains 4 workplanes.
They were designed to specifically for driving angular constraints.
Constraints are a method of limiting or restricting an elements movement.
4 Types of constraints in Revit
Constraints don't have to be static, they can be driven by a parameter value. Additionally a parameter’s value can also be driven by a formula.
A Parameter is a setting that determines the appearance or behavior of an element, type, or view.
Parameters store and communicate information about all elements in a model. Parameters are used to define and modify elements, as well as to communicate model information in tags and schedules.
3 basic types:
System, Family and Shared parameters…
Are built in parameters defined in the software, they can't be removed or renamed, but they do schedule.
Note: when the parameter is selected in the Family Types dialog modify button is greyed out.
Are user based parameters that don't schedule.
Are user based parameter with a shared definition and GUID that do schedule. The definition is stored in a shared parameter file, so the parameter can be loaded into many families.
Type Based Parameters:
Predefined size typical that can be found in a manufactures catalog.
Instance Based Parameters:
Variable based user input parameters used on items the can come in any length, like a wide flange beam is manufactured to any length the structure engineer requires. In this case the length of the beam is instance based.
Instance based parameter that can extract a value from a generic condition. This type of parameter can only be a length or angle.
There are 4 types of elements:
Model Elements: (available in all views)
View Specific: (available in the views created in)
Each have element properties, for example:
These properties can be used to control how an element looks and is displayed, along with other properties of that element.
How do I decide which template to start from?
Don't select a template just based on the category, thinking about the functionality first will give you more options.
Functionality is not tied to the category but is tied to the template.
The category adds the family parameters, built in parameters and subcategories required for that category. Also this selection will effect how the family schedules.
Note: It does take some learning all the special cases in Revit.
2D vs. 3D family?
2D – What is the use?
3D – Does the family require specific functionality?
Yes – What is the special functionality for?
No – Does the family require a host?
Yes – Which host?
No – Then chose from:
Then choose a category.
Many of the family template are open to multiple categories giving you different functionality depending on your choices.
User wants to build an escalator
If they follow the category first, the user will have adjust the escalator height on placement and any time the floor to floor height changes.
If they follow the functionality first you can end up with a 2 level aware escalator that re-adjust its size automatically when the floor to floor height changes.
Template behaviors vs. category behaviors
Template have behaviors built in in relation to hosting, placement methods or even special editors
While categories have behaviors that are controlled by the settings in the Family Parameters under Family Category and Parameters dialog.
Changing the category changes the options available in the Family Parameters list. Some of the options include "Always Vertical", "Cut with Voids When Loaded" and "Shared"
Additionally setting the category changes the available built in sub-categories and parameters.
Visual example – Generic Model to Doors
The “process” for building families is the most important aspect of family creation that one needs to learn.
A successful piece of content meets all the users needs for BIM.
Build not only for the user but how the information will be use along the whole BIM life cycle.
Additionally try to meet all requirements for:
Type Catalogs are an external group of types or catalog of a family in a delimited text format. Type catalog allow the user to selectively load a type from a long list.
The type catalog name must match the family name but with a .txt extension.
The simplest way to create a type catalog is to export the current types by:
Click "R" > Export > (Family Types).
Open the file in a text editor and modify as needed.
,Manufacturer##other##,Length##length##centimeters,Width##length##centimeters, Height##length##centimeters MA36x30,Revit,36.5,2.75,30 MA40x24,Revit,40.5,3.25,24
The first line defines the delimiter and the parameters in the type catalog.
The first character of the first line is the delimiter, in this case a comma ','.
<parameter name>##<parameter type>##<units>,
The next lines are the catalog entries:
Parameter Declaration Table
Reference planes have a property called “Is Reference”. By setting this property, you specify that the reference plane can be dimensioned or snapped to when you place a family into a project.
Additionally labeled instance parameters attached to reference planes with weak or strong “Is Reference” will allow shape handles for the user to control.
A “strong reference” has the highest priority for dimensioning and snapping.
For example, you create a window family and place it into a project. As you are placing the family, temporary dimensions snap to any strong references in the family. When you select the family in the project, temporary dimensions appear at the strong references. If you place a permanent dimension, the strong references in the window geometry highlight first. A strong reference takes precedence over a wall reference point (such as its centerline).
A “Weak reference” has the lowest priority for dimensioning and snapping. When you place the family into the project and dimension to it, you may need to press Tab to select a weak reference, as any strong references highlight first.
A “Not a reference” is not visible in the project environment so you cannot dimension or snap to those locations in a project.
All named “Is Reference”: Left, Right, Top… are considered strong references.
But the “Name” of the reference plane has no relation to the function of the “Is Reference” parameter.
What are we going to do in this class?
Planning questions to answer:
Build in levels of detail or complexity using the Bones, Muscle and Skin methodology.
Process (short version):
Order of Complexity:
Nesting enables the use of reusable parts in the family editor.
In order to provide the associated images, here are the complete illustrated Key Family Concepts and Parametric Family slide decks.
Steve's presentations above cover the key family editor concepts from a user point of view.
How to make use of this functionality programmatically is a large important topic that has been frequently discussed here in the past, e.g. looking at:
To supplement the existing blog posts and Steve's product usage presentation for add-in developers, we decided to add new improved demonstrations of the following fundamental programming concepts to this overview:
This is where it gets really interesting for you, I hope.
Here is a snapshot of the current fully functional state of my FamilyApi sample add-in implementing the following three external commands providing a nice clean implementation of those concepts, plus an external application wrapper defining a compact user interface to access and launch them:
The detailed explanation of these three commands is still forthcoming, hopefully tomorrow, so keep your eyes peeled.