What's New in the Revit 2010 API: Finally Families!

(Part of the What's New in Revit 2010 API series)





Probably the biggest single improvement to the Revit API in 2010 is a wide variety of enhancements to supporting Revit Families - and it's been a long time coming.


Until now, the support for families has been spotty - for example, you could open family files as documents - but you couldn't see the types inside them - or really do anything with them.

Autodesk has implemented a dizzying amount of capabilities to help with:

• Analyzing Families


• Creating new Families (geometry, parametrics and all!)


• Reading and Writing Family Types, parameters, and even formulas


• Ability to examine Families embedded in projects


• Read/Write Family Element Visibility


• Control the loading behavior of families
  

Personally, after doing a number of Family manipulation projects which had to be done with Journal Files - I'm excited to be back dealing with the API!

Enhanced Document class
The core concept of working with families in the Revit 2010 API is the improved "Document" class. The Document class still represents both Project and Family documents, but it has been enhanced with the following properties and methods:

• EditFamily( family) - similar to context-menu Edit Family command


• FamilyManager (provides access to the types, parameters, and formulas related to the family)


• OwnerFamily - to deal with nested family components
  

The Family Manager is able to do a wide variety of tasks, including full control of adding, removing and renaming types, adding and removing parameters, and setting values and formulas.

Creating Solids

Creation of elements will be covered in more depth in another post - but suffice it to say there is an impressive list of things that you can programmatically create through the new APIs, including:

• Extrusions


• Blends


• Sweeps


• Loft


• Model Text


• Openings


• Revolutions


• Dimensions


• and much more

Visibility Settings

For those of you who are not familiar with content building, one of the most critical topics to "get right" when building content is the visibilty settings:




Each element in a family has visibility settings - both which levels of detail it appears in as well as whether it appears in different types of views. These options are critical to building good content. For example, if you have intricate details in your family, consider if they should only be shown in "Fine" detail views. Also, if you have 3D solid content, one alternative is to NOT show the 3D solid in Plan views - instead, you would use 2D linework in Plan View. These approaches can make a SUBSTANTIAL difference in the performance of Revit - particularly as your building model grows.

While there had been undocumented parameter access to this information before, the new FamilyElementVisibility class makes this information easy to access for each element in a family.

Loading Control
If you've ever written an application that loads families into a project, you may have run into the problem of what happens when the family already exists in the project (particularly if you're using shared families). While the "DialogBox" event controls used to give a poor-but-workable method to suppress Revit's pop-up dialog boxes, the new loading methods give far better control over what happens.

The new LoadFamily method signature:

Family = Document.LoadFamily( string path, IFamilyLoadOptions options );
or
Family = Document.LoadFamily( Document familyDocument, IFamilyLoadOptions options);

The IFamilyLoadOptions, as implemented by the RevitUIFamilyLoad class, give you events for family loading as well as specific behavior control for whether to update the family, and whether to override parameters.


What Can You Do With All This?

There are a variety of capabilities that these features open to you... First of all, I suspect that a variety of new content tools will become available to better manage your content. If you manage a great deal of content, and need to make large-scale changes to content, these features will make it happen.

It IS possible now to extract project families back to RFAs - as well as doing better comparisons than previously possible between "embedded" families and standalone families.

Another big step for Autodesk - they now allow you to use the API insert a DWG file into a family. This had previously been deliberately disabled.

Hypothetically speaking, this means that you could possibly crank out thousands of families based on existing DWGs. But before you consider doing this - let me be among the voices saying - DON'T. Our research indicates that families created using DWG files are fundamentally terrible - they are "heavy", "slow", and "dumb". Almost all firms using Revit have discovered this - and are systematically removing these families from their library. Doing content correctly would be a great other post - and the API now gives you the tools to do things right... Please try to do the right thing!

-Matt