Writing Family Instances with the Revit Writer

Introduction

The Revit Writer is capable of writing non-hosted family instances. This article will highlight some notable points on Revit family instances, and will provide step-by-step instructions on how to write non-hosted family instances with the Revit writer in FME Workbench 2024.x.

What is a Revit Family?

A Revit family is a group of objects combined to create a single, reusable model component. Each family can be created and then saved as a stand-alone .rfa file, for use and reuse in a single project or across multiple projects. Employing the use of families makes object standardization across projects much more efficient.

Types of Revit Families

There are three different types of Revit families to be aware of:

• System Families: those built-in families that Revit uses for the most basic building elements, such as walls, floors, roofs, and ceilings;
• Loadable Families: custom-built families that can be created external to a project, and are often standard to most projects in a user group / organization. These families are typically used for objects like furniture, equipment, and fixtures.
• In-Place Families: custom-built families that are project-specific and so are not expected to be reused outside of the target project. These families do not exist as stand-alone .rfa files.

Currently, FME’s Revit writer is capable of writing loadable families.

Hosted vs Non-Hosted Revit Families

Some family instances require a host element for their placement in a Revit model. These family instances are called hosted family instances. A good example of a hosted family instance is a window. In Revit, windows are required to be hosted on walls by default. 

Other family instances do not require a host element for their placement in a model, and so are called non-hosted family instances. Plumbing fittings are a good example of family instances that can be non-hosted, to accommodate a wide variety of application scenarios in a given model.

It’s important to understand the difference between hosted and non-hosted family instances when working with Revit models in FME, as FME’s Revit writer can currently write non-hosted family instances only.

How does FME’s Revit Writer Produce Family Instances?

At a high level, FME’s Revit writer will recognize as a family instance any oriented point feature that contains valid values for two required Revit family attributes. The Revit writer will then use these required attribute values to create the specified family instance in the target model and will use the input point feature as the resultant family instance’s origin point. The created family instance will be rotated based on the orientation of the input point feature.

The two attributes required for defining a Revit family instance feature in FME are:

• Family: specifies which Revit family the instance should belong to; and
• FamilyType specifies which type within the identified Revit family the instance should be. A family can have multiple types, each of which consists of a unique set of properties. A good example of this idea is a chair family. One chair family can have many types, each varying from other types in size, style, material, or other key family-related properties.

An additional optional attribute, StructuralType, can also be defined for family instance features. This attribute's value specifies the Structural Type of the instance feature. If this attribute is not present, the Revit writer will treat each input feature as Non-Structural by default.

Since Revit families can be saved independently of a Revit project as .rfa files, the Revit writer’s Load Additional Families parameter can be used to select a directory containing .rfa files of interest. Every .rfa file found in this target directory will be loaded and made available to the writer. This .rfa loading functionality is important where the Revit template file specified on the Revit writer does not contain a family instance of some (or all) of the writer's input family instance features.    

The RevitStyler Transformer

Writing Revit family instances in FME can be simplified by adding the RevitStyler transformer to a workflow. The RevitStyler can perform the following three key functions to support the Revit writer:

• Turn any feature with point geometry into a family instance, by creating and populating the required family instance attributes;
• Select a family and family type from a Revit project (.rvt) or family (.rfa) file; and
• Set a family instance’s rotation

Only point features will be converted to family instances; if features with other geometry types are input into the RevitStyler, they will not be affected. For additional information on the RevitStyler, please see the related FME Form documentation.

Revit-to-Revit Translations and Family Instances

FME’s Revit reader is capable of reading loadable and system family instances that are non-hosted, as point features. To produce these point features, users should enable the Output Family Instances As Family Reference Points parameter on the Revit reader. Resultant point features can be passed along to the Revit writer as inputs for writing family instances to the same source model, or for writing to another model.

Exercise: Create and Write Revit Family Instances

The following exercise introduces users to a simple method for creating and writing Revit family instances. During this exercise, users will create two point features which will both become side table family instances. A rotation will be applied to one of the side tables to demonstrate the Angle Axis Rotation functionality of the RevitStyler. Both of these family instances will be written to a new Revit project file.

Before beginning, please navigate to the Autodesk Revit 2024 documentation and download the Sample Project File (rac_basic_sample_project.rvt) and the Sample Family File (rac_basic_sample_family.rfa). The data shown in the screenshots below is for informational purposes only and is not provided by Safe Software. 

1. Open FME Workbench 

Open FME Workbench 2024.0 or newer, and choose to begin with a blank canvas.

2. Add a Creator

Add a Creator to the main workspace by first typing "Creator" anywhere on the blank canvas. In the Quick Add dialog that opens, double-click on the Creator in the list at left. A new Creator transformer will be added to the canvas. 

3. Configure the Creator's Parameters

Configure the Creator's parameters by double-clicking on the Creator. In the Parameters dialog, click the ellipsis next to the Geometry Object parameter. In the Geometry Creator dialog, choose  Point from the list of geometry types on the left. Enable the 3D coordinates option at the bottom of the dialog, and then enter X, Y, and Z values of 11, -50, and 0, respectively. 

Click OK on the Geometry Creator dialog to return to the Parameters dialog. Now choose EPSG:4326 as the value for the Coordinate System parameter.

Leave all other Creator parameter values as their defaults, and select OK on the Parameters dialog to return to the main canvas.

4. Add a Another Creator

Add another Creator to the canvas. In the Creator_2 parameters, create a 3D Point geometry feature with the X, Y, and Z values of 5, -46, and 0, respectively. Then set the Coordinate System as EPSG:4326. 

5. Add a RevitStyler

Add a RevitStyler to the canvas and connect it to the first Creator. This RevitStyler will be configured to transform one point feature into a Revit side table family instance with no rotation applied. 

6. Configure the RevitStyler 

Configure the RevitStyler to produce the first side table family instance. First, double-click on the RevitStyler to access its Parameters dialog. Next, under the Family Instances parameter group, click the ellipsis next to the Revit Project/Family File parameter, and navigate to the racbasicsamplefamily.rfa file that was downloaded at the start of this exercise. This Revit Family file contains the components necessary to construct new side table family instances. 

Once this .rfa file loads, click the ellipsis next to the Family Name parameter, and choose racbasicsamplefamily. Then click the ellipsis next to the Family Type parameter, and choose 0762 x 0762mm.

Leave all other RevitStyler parameters as their default values, and select OK at bottom right of the Parameters dialog. 

7. Add a Second RevitStyler

Add a second RevitStyler to the canvas and connect it to the Creator_2. This second RevitStyler will be configured to transform the remaining point feature into a rotated side table family instance. 

8. Configure the Second RevitStyler

Configure the second RevitStyler to produce a rotated side table family instance. In the RevitStyler_2 parameters, under the Family Instances parameter group, click the ellipsis next to the Revit Project/Family File parameter, and navigate to the same racbasicsamplefamily.rfa file applied to the first RevitStyler, above.  

Now click the ellipsis next to the Family Name parameter and choose racbasicsamplefamily. Then click the ellipsis next to the Family Type parameter, and choose 0762 x 0762mm.

Expand the Axis Angle Rotation parameter group, and enter a value of 1 for the Orientation Axis X parameter. This will indicate that a rotation should occur about the x-axis. Enter a value of 60 for the Rotation parameter. The Rotation parameter's value indicates the degrees of rotation that will be applied to the feature about the selected axis, and following the right hand rule.

9. Add a Revit Writer

Add an Autodesk Revit writer to the canvas. In the Add Writer dialog, click the ellipsis next to the Dataset parameter. Navigate to a location where the written Revit project file will be stored, and give the project file a name. Select Save to return to the Add Writer dialog.

Next, select the Parameters button on the Add Writer dialog. The Autodesk Revit Parameters dialog will open. Click the ellipsis to the right of the Template File parameter, and navigate to the rac_basic_sample_project.rvt Revit project file downloaded at the beginning of this exercise. The Revit writer will use this project as its starting point, and will add the two created side table family instances to the project. The edited project will then be saved under the file name and location specified by the writer's Dataset parameter.

Finally, enable the Load Additional Families parameter. Click the ellipsis next to the Family Files Directory parameter and navigate to the parent folder which contains the rac_basic_sample_family.rfa file downloaded at the beginning of this exercise. 

Select OK on the Autodesk Revit Parameters dialog to return to the Add Writer dialog. Leave the Revit Category Definition set to Automatic and select OK on the Add Writer dialog. Select OK in the Feature Type dialog that pops open to add the Revit writer and its feature type to the workspace.

Connect both RevitStylers to the Revit writer feature type. 

Note on family files: The Family Files Directory parameter of the Revit writer will read all of the files contained in the specified directory, and will load any .rfa files found therein to help write the family instances of features input to the writer. This parameter is particularly useful for writing those input family instances where the specified Revit template file does not have a matching family instance.

It is therefore important to ensure that all of the families referenced by features input to the Revit writer:

• are part of the Revit template file specified by the Template File parameter; or
• have their associated Revit family files stored together at the location specified by the Revit writer's Family Files Directory parameter.

If an input feature references a family whose family definition is not available (either in the Template File or in the Family Files Directory), that feature will be skipped at writing, and a Warning message similar to the following will appear in the translation log:

Revit Native Writer: Unable to locate family 'FireHydrant' with family type 'Type 2' in file
'<PATH_TO_REVIT_TEMPLATE_FILE>'or loaded family files. Skipping feature

10. Run the workspace

Run the workspace by selecting the Run icon in the main Workbench ribbon. 

Once the translation completes, single-click the Revit writer feature type on canvas to open the mini menu and select the View Written Data icon to view the written project file in the Visual Preview window.

In the Visual Preview window that opens, deselect the Feature Information view. Select the Display Control view, the Graphics view and the Table view. These views can be enabled / disabled by toggling the icons along Visual Preview's left-side pane.

Expand the Visual Preview window so that the contents of all three enabled views are easier to select. Next, in the Display Control view, disable all but the Architectural.Furniture category. In the Table view, single-click the ObjectId field name such that the features are sorted by ObjectId in descending order. The top two features now shown in Table view should both have a Family value of racbasicsamplefamily. These two features are the newly written side tables. Select one of these two new family instances to highlight its record in Table view.

In Graphics view, select the 3D icon along the top ribbon, and then select the Zoom to Selected Feature icon. The Graphics view display will zoom into the newly written family instance that was selected in Table view.

Use the Zoom, Orbit and Pan options along the Graphics view ribbon to zoom out slightly and inspect the two new family instances. Users can also use their mouse wheel to zoom and orbit the display by rolling or clicking the wheel, respectively. To deselect the highlighted feature, choose the Select icon in the Graphics view ribbon, and then click in a blank display area.  

The Visual Preview window provides a quick way to view written data within FME Workbench. Alternatively, users can open the written Revit project file in FME Data Inspector by selecting the Open In Data Inspector icon. This icon is located with the Display Control, Table View, and Graphics View icons found along the left-side pane of the Visual Preview window.

FME Data Inspector is a stand-alone application that ships with FME Form, and offers a large viewing area with a full suite of tools optimized for inspecting data pre- and post-translation. Selecting the Open in Data Inspector icon in the Visual Preview window of FME Workbench will open the written project file in a new instance of FME Data Inspector.

Users can then disable all but the Architectural.Furniture Revit category in the FME Data Inspector's Display Control pane, select the 3D icon along the main ribbon, and use the other available main ribbon tools in FME Data Inspector to review the two newly written Revit family instances.

To view the .rvt file output by this exercise in Revit, open the output project file in Revit 2024. In general, the release year of the FME product used to write a Revit project file corresponds to the release year of Revit for which the written project has been optimized. Since the project file output by this exercise's workflow was written by FME Workbench 2024.x, it has been optimized for compatibility with Revit 2024.

Additional Resources

Revit Writing in FME Form

Integrating FME into Dynamo for Revit

Revit Geolocation

Data Attribution

The data used in this article is for informational purposes only and is not provided. To obtain a sample dataset to work with, please see the Autodesk Revit 2024 documentation.