Here is a rather lengthy and rich post to start off the week, describing the new family API introduced in Revit 2010 and including both an overview and in-depth information.
These are the main topics covered:
The text presented here is also a script for the Revit Family API slide deck which was used for the webcast mentioned at the end of this post. If a picture says more than a thousand words to you, then you should download that slide deck, which will provide a couple of thousand words' worth of images to accompany this raw text.
The concept of families is an enormous strength of Revit, but until Revit 2010, no programming access was available in the family context. Therefore, two large and completely disjunct developer communities have evolved around the Revit products, creating either:
The Family API was the top wish list item and was made available for the first time in Revit 2010. It provides huge potential for synergy uniting the two separate camps. It enables:
A non-trivial family can have a complex internal structure and many decisions need to be taken. A large body of experience around building families and family libraries has been developed before the introduction of the API. It is useful to gather some experience creating families manually before implementing code to do so automatically. Just like the standard Revit API, almost all the features provided by the family API are available through the user interface as well.
Before discussing the family API, it is important to understand the basics of Revit families and their definition.
A Revit family is a graphic representation of building objects and symbols. It can include geometry in 2D or 3D as well as data that supports the definition and creation of object instances. A family defines one or more types or symbols. A type or symbol can be inserted into the project to create a family instance.
There are three different classes of families, system, standard and in-place:
The new family API provided in Revit 2010 addresses the standard families.
A new family is always based on a family template file, if created from scratch, or on an existing family, which is enhanced in some way. Regardless of whether you are using the UI or API, the first thing you will need to decide is which template or family file you want to begin with.
You need to choose which approach to take, as well as which template or family file to start with. There are plenty of templates to choose from. Other decisions that need to be taken and which influence this choice include
Just like the Revit product, Revit families also come in three flavours for architecture, MEP (mechanical, engineering, and plumbing), and structure. Most of the functionality is common to all three. Here are some aspects of the flavours:
Revit Architecture:
Revit Structure:
Revit MEP:
Revit offers six basic family editors:
Of the six basic family editors, the conceptual mass creation one is new to 2010. Depending on the editor, you will see a different set of available tools and building blocks. For instance, you will see tools to create forms in the model editor, but not in the annotation one. If you are using the truss editor, you will have access to the top and bottom chord, which will be shown in the model editor.
Each family editor is tied to the chosen family template and provides a specific feature set:
Families are a powerful feature in Revit. Creating a family can be fun, and it can also be complex. When it becomes complex, it requires good planning. Here are some suggestions for a process for building families by the Autodesk Revit content manager Steve Campbell. It describes the manual definition of a family. The same applies to a programmatic approach as well. A key to understanding the family API is to understand the UI.
It is highly recommended to follow this structured process when building families. It needs to be learned and practiced. Systematically following this process is one of the most important aspects of family creation.
Process order:
You can create quite complex objects and behaviour using Revit families. Here are a few of the possibilities:
Formulas can be used to control behaviour, visibility, arrays, e.g. to define arrays of bolts depending on the size of a plate.
Arraying nested components allows the user to create families with repeatable elements across an array that can resize based on user input or rules. For example, a bookshelf with arrayed shelves, mullion patterns based on rules, and open web joists that adjust based on length and height.
Advanced nesting can make use of nested families with family type parameters that can provide flexible components with swappable sub-components such as nested door panels, frames, hardware, playground equipment, swappable panels and components.
Reference lines allow geometry to move about in an angular fashion. They contain two endpoints and two built in work planes that can be parametrically controlled. Some simple examples include a door swing that can change the opening angle, or a light fixture head that moves and points. A more complex example is an excavator arm that can bend and rotate about three or more pivot points.
Now that the basics of Revit families are clear, we can look at the new access to this functionality provided by the new family API.
Exposure of the family API is probably the most important enhancement to the Revit API in 2010. The concept of component family is a unique feature and strength of Revit. This was the most wanted feature in the Revit API community and we expect the effect and growth in possibilities with the availability of family API will be dramatic.
An obvious opportunity provided by the new family API is the automatic generation of content from databases or other library sources.
It is also possible to extract a family definition out of a project and store it back into an external family file.
The document Revit Platform API Changes and Additions.doc in the Revit SDK folder provides an overview of the family API.
Family API specific samples are located in the Revit SDK samples FamilyCreation subfolder.
Here are some of the new supported features:
The Revit API Document now has some added methods and properties for managing families:
Within a family document, the family manager class provides the following new functionality:
The FamilyCreate property on the family document returns a FamilyItemFactory instance. This family item factory object is a utility object used to create new instances of elements within the family document. Just like other Revit elements, these are instantiated using dedicated methods instead of the .NET new operator. This ensures that the elements created are correctly added to and hooked up within the family document. A wide range of elements types can be created, including alignments, dimensioning, annotation, curves, levels, and solid forms for conceptual design.
The family item factory utility object
Elements types that can be created include:
A critical topic when building family content are the visibility settings. They are now accessible for each element in a family through the new FamilyElementVisibility class.
Each element in a family has its own visibility settings which define which levels of detail and which types of views it appears in. These options are critical to building good content. For example, intricate details of a family should only be visible in the fine detail views. 3D solid content could optionally be suppressed in plan views, where light weight 2D line work could be displayed instead. Such an approach can make a substantial performance difference, especially in large building models.
Every element in the family has own visibility settings managed by the FamilyElementVisibility class defining:
The Document.LoadFamily method has been enhanced and new overloads have been added, which can help to handle situations such as when a family already exists in the project. The following overloads are now provided:
The IFamilyLoadOptions argument to the last overload defines an interface which specifies two call-backs for handling family load situations: OnFamilyFound and OnSharedFamilyFound. These are called when a family or a shared family is already present in the target document.
A number of new samples illustrating the family API have been added to the Revit SDK. They are located in the FamilyCreation subfolder in the SDK Samples directory.
AutoJoin automatically joins geometry of multiple generic forms for use in family modelling and massing. It uses the method Document.CombineElements to join geometry between overlapping generic forms. It also includes a utility method to check geometry object overlap, based on the Face.Intersect(Curve) method.
AutoParameter implements batch mode automatic addition of shared or non-shared parameters to one or more family documents. It optionally processes either the currently active family document or all families in a specified folder. It uses the FamilyManager class AddParameter methods and reads its input data from parameter text files in a format similar to the Revit shared parameter files.
CreateAirHandler is a Revit MEP sample to create an air handling unit including MEP pipe and duct connectors. It shows how to check the template family category to verify that a valid starting point is selected. It make use of the FamilyItemFactory class NewExtrusion, NewPipeConnector, and NewDuctConnector methods, sets up the proper connector parameters, and uses Document.CombineElements to join the extrusions to make up the air handler body.
CreateTruss is a Revit Structure sample that creates a mono truss in a truss family document. The truss curves are created using NewModelCurve, the truss type is set through the ModelCurve TrussCurveType property, and constraints are added to the truss curves with NewAlignment.
DWGFamilyCreation shows how to import a DWG file into a family document add two type parameters to the imported instance: DWGFileName specifying the DWG file name, and ImportTime storing the data and time when it was imported.
GenericModelCreation creates a generic model using extrusion, blend, revolution, sweep and swept blend elements. It checks that the open document is indeed a family one or otherwise creates a new family document. It exercises the CreateSketchPlane, NewLineBound, and FamilyItemFactory methods to create profiles and shapes.
The TypeRegeneration sample uses the FamilyManager Types property to determine all types defined in the current family document, and CurrentType to iterate through them. It reports whether all types regenerated successfully, and logs any errors that occurred to a file.
ValidateParameters checks whether every type in the current family document has valid values for certain parameters and logs the results to a file. This sample can be run in two modes, either as an external application subscribing to DocumentSaving and DocumentSavingAs events to run the check automatically every time a document is opened, or as an external command to be launched manually when required.
WindowWizard shows how to create a new window family via a wizard style user interface. It needs to be started in a window family template, e.g. Metric Window.rft. It prompts the user to define input dimensions for various window parameters and materials, and then creates the required geometry, constraints and types using elements including extrusions, alignments, dimensions, reference planes, and family types.
The Revit Family API Labs is a collection of exercises which introduce you step by step to the creation of a column family. The objective is to learn the basics of the family API. The labs start with the basics and then proceed to more advanced aspects. Full documentation of and instructions for each step are included in separate documents for C# and VB.
Classes and methods:
doc.IsFamilyDocument() doc.OwnerFamily.FamilyCategory.Name doc.FamilyCreate.NewExtrusion() doc.FamilyCreate.NewAlignment() familyMgr = doc.FamilyManager familyMgr.NewType() familyMgr.Parameter(); familyMgr.Set()
Classes and methods:
doc.FamilyCreate.NewReferencePlane() familyMgr.AddParameter() doc.FamilyCreate.NewDimension()
Classes and methods:
familyMgr.SetFormula()
pSolid.Parameter("Material")
familyMgr.AddParameter("MyColumnFinish", BuiltInParameterGroup.PG_MATERIALS, ParameterType.Material, True)
familyMgr.AssociateElementParameterToFamilyParameter()
Classes and methods:
doc.FamilyCreate.NewSymbolicCurve() doc.FamilyCreate.NewModelCurve() FamilyElementVisibility(FamilyElementVisibilityType.ViewSpecific/Model) FamilyElementVisibility.IsShownInFine, etc. pLine.SetVisibility(pFamilyElementVisibility)
Here is an overview of some available resources for further learning:
We held a successful webcast on the Revit Family API on Thursday July 23rd 2009. The supporting material and recording from this webcast is now available. To access the material from any ADN webcast, you can go to the ADN training schedule site and click on the corresponding download link. You can find this specific webcast by filtering for 'Revit Family API'. Here is a direct link to download the webcast material, which includes the following items: