FamilyInstances

FamilyInstance objects include Beams, Braces, Columns, Furniture, Massing, and more. The FamilyInstance object provides more detailed properties so that the family instance type and appearance in the project can be changed.

Location-Related Properties

Location-related properties show the physical and geometric characteristics of FamilyInstance objects, such as orientation, rotation and location.

Orientation

The face orientation or hand orientation can be changed for some FamilyInstance objects. For example, a door can face the outside or the inside of a room or wall and it can be placed with the handle on the left side or the right side. The following table compares door, window, and desk family instances.

Table 29: Compare Family Instances

Boolean Property

Door

Window (Fixed: 36"w × 72"h)

Desk

CanFlipFacing

True

True

False

CanFlipHand

True

False

False

If CanFlipFacing or CanFlipHand is true, you can call the flipFacing() or flipHand() methods respectively. These methods can change the facing orientation or hand orientation respectively. Otherwise, the methods do nothing and return False.

When changing orientation, remember that some types of windows can change both hand orientation and facing orientation, such as a Casement 3x3 with Trim family.

There are four different facing orientation and hand orientation combinations for doors. See the following picture for the combinations and the corresponding Boolean values are in the following table.

Figure 44: Doors with different Facing and Hand Orientations

Table 30: Different Instances of the Same Type

Boolean Property

Door 1

Door 2

Door 3

Door 4

FacingFlipped

False

True

False

True

HandFlipped

False

True

True

False

Orientation - Work Plane

The work plane orientation for a FamilyInstance can be changed, as well. If CanFlipWorkPlane is true, you can set the IsWorkPlaneFlipped property. Attempting to set this property for a FamilyInstance that does not allow the work plane to be flipped will result in an exception.

Rotation - Mirrored

The Mirrored property indicates whether the FamilyInstance object has been mirrored.

Table 31: Door Mirrored Property

Boolean Property

Door 1

Door 2

Door 3

Door 4

Mirrored

False

False

True

True

In the previous door example, the Mirrored property for Door 1 and Door 2 is False, while for both Door 3 and Door 4 it is True. This is because when you create a door in the Revit project, the default result is either Door 1 or Door 2. To create a door like Door 3 or Door 4, you must flip the Door 1 and Door 2 hand orientation respectively. The flip operation is like a mirror transformation, which is why the Door 3 and Door 4 Mirrored property is True.

For more information about using the Mirror() method in Revit, refer to the Editing Elements chapter.

Rotation - CanRotate and rotate()

The family instance Boolean CanRotate property is used to test whether the family instance can be rotated 180 degrees. This depends on the family to which the instance belongs. For example, in the following picture, the CanRotate properties for Window 1 (Casement 3×3 with Trim: 36"×72") and Door 1 (Double-Glass 2: 72"×82") are true, while Window 2 (Fixed: 36"w × 72"h) is false.

Figure 45: Changes after rotate()

If CanRotate is true, you can call the family instance rotate() method, which flips the family instance by 180 degrees. Otherwise, the method does nothing and returns False. The previous picture also shows the Window 1 and Door 1 states after executing the rotate() method.

Recall from the Rotating elements section earlier in this document, that family instances (and other elements) can be rotated a user-specified angle usingElementTransformUtils.RotateElement() and ElementTransformUtils.RotateElements().

Location

The Location property determines the physical location of an instance in a project. An instance can have a point location or a line location.

The following characteristics apply to Location:

  • A point location is a LocationPoint class object - A footing, a door, or a table has a point location

  • A line location is a LocationCurve class object - A beam has a line location.

  • They are both subclasses of the Location class.

For more information about Location, refer to Editing Elements.

Host and HostFace

Host and HostFace are both FamilyInstance properties.

Host

A FamilyInstance object has a Host property that returns its hosting element.

Some FamilyInstance objects do not have host elements, such as Tables and other furniture, so the Host property returns nothing because no host elements are created. However, other objects, such as doors and windows, must have host elements. In this case the Host property returns a wall Element in which the window or the door is located. See the following picture.

Figure 46: Doors and windows hosted in a wall

HostFace

The HostFace property gets the reference to the host face of the family instance, or if the instance is placed on a work plane, the reference to the geometry face underlying the work plane. This property will return a null reference if the work plane is not referencing other geometry, or if the instance is not hosted on a face or work plane.

Subcomponent and Supercomponent

The FamilyInstance.GetSubComponentIds() method returns the ElementIds of family instances loaded into that family. When an instance of 'Table-Dining Round w Chairs.rfa' is placed in a project, the ElementIds of the set of chairs are returned by the GetSubComponentIds() method.

The SuperComponent property returns the family instance's parent component. In 'Table-Dining Round w Chairs.rfa', the family instance supercomponent for each nested chair is the instance of 'Table-Dining Round w Chairs.rfa'.

Code Region 12-1: Getting SubComponents and SuperComponent from FamilyInstance

public void GetSubAndSuperComponents(FamilyInstance familyInstance)
{
    ICollection<ElementId> subElemSet = familyInstance.GetSubComponentIds();
    if (subElemSet != null)
    {
        string subElems = "";
        foreach (Autodesk.Revit.DB.ElementId ee in subElemSet)
        {
            FamilyInstance f = familyInstance.Document.GetElement(ee) as FamilyInstance;
            subElems = subElems + f.Name + "\n";
        }
        TaskDialog.Show("Revit","Subcomponent count = " + subElemSet.Count + "\n" + subElems);
    }
    FamilyInstance super = familyInstance.SuperComponent as FamilyInstance;
    if (super != null)
    {
        TaskDialog.Show("Revit","SUPER component: " + super.Name);
    }
}

Geometry

Sometimes the geometry of a FamilyInstance object is modified by joins, cuts, coping, extensions, or other post-processing that occurs in Revit. The FamilyInstance.HasModifiedGeometry() method identifies if the geometry of this FamilyInstance has been modified from the automatically generated default. The GetOriginalGeometry() method will return the original geometry of the instance prior to any modifications that may have occurred. To get the current geometry of the instance, use the Geometry property inherited from the Element class.

Spatial Element Calculation Points

The FamilyInstance has several members for reading the information about spatial calculation point(s) directly from the family instance. The HasSpatialElementCalculationPoint property identifies if this instance has a single SpatialElementCalculationPoint used as the search point for Revit to identify if the instance is inside a room or space. If true, the GetSpatialElementCalculationPoint() method will return the location of the calculation point for this instance as an XYZ point.

The HasSpatialElementFromToCalculationPoints property identifies if this instance has a pair of SpatialElementCalculationPoints used as the search points for Revit to identify if the instance lies between up to two rooms or spaces. The points determine which room or space is considered the "from" and which is considered the "to" for a family instance which connects two rooms or spaces, such as a door or window. When this property is true, the GetSpatialElementFromToCalculationPoints() method returns the locations for the calculation points for this instance as a list of XYZ points.

Other Properties

The properties in this section are specific to Revit Architecture and Revit Structure. They are covered thoroughly in their respective chapters.

Room Information

FamilyInstance properties include Room, FromRoom, and ToRoom. For more information about Room, refer to Revit Architecture.

Space Information

FamilyInstance has a Space property for identifying the space that holds an instance in MEP.

Revit Structure Related Analytical Model

The GetAnalyticalModel() method retrieves the family instance structural analytical model.

For more information about AnalyticalModel refer to Revit Structure.

Creating FamilyInstance Objects

Typically a FamilyInstance object is created using one of the twelve overload methods of Autodesk.Revit.Creation.Document called NewFamilyInstance(). The choice of which overload to use depends not only on the category of the instance, but also other characteristics of the placement like whether it should be hosted, placed relative to a reference level, or placed directly on a particular face. The details are included in Table 32 - Options for creating instance with NewFamilyInstance() below.

Some FamilyInstance objects require more than one location to be created. In these cases, it is more appropriate to use the more detailed creation method provided by this object (see Table 33 - Options for creating instances with other methods below). If the instance is not created, an exception is thrown. The type/symbol used must be loaded into the project before the method is called.

All overloads for NewFamilyInstance() check to ensure that the input FamilySymbol is active (FamilySymbol.IsActive). If the input FamilySymbol is inactive, the method will throw an ArgumentException. Symbols that are not used in the document may be deactivated to conserve memory and regeneration time. When the symbol is inactive, its geometry is empty and cannot be accessed. In order to access the geometry of a symbol that is not active in the document, the symbol should first be activated by calling FamilySymbol.Activate().

Table 32 - Options for creating instance with NewFamilyInstance()

Category NewFamilyInstance() parameters Comments

Air Terminals

Boundary Conditions

Casework

Communication Devices

Data Devices

Electrical Equipment

Electrical Fixtures

Entourage

Fire Alarm Devices

Furniture

Furniture Systems

Generic Models

Lighting Devices

Lighting Fixtures

Mass

Mechanical Equipment

Nurse Call Devices

Parking

Planting

Plumbing Fixtures

Security Devices

Site

Specialty Equipment

Sprinklers

Structural Connections

Structural Foundations

Structural Stiffeners

Telephone Devices

XYZ, FamilySymbol, StructuralType Creates the instance in an arbitrary location without reference to a level or host element.
XYZ, FamilySymbol, Element, StructuralType If it is to be hosted on a wall, floor or ceiling
XYZ, FamilySymbol, XYZ, Element, StructuralType If it is to be hosted on a wall, floor, or ceiling, and needs to be oriented in a non-default direction
XYZ, FamilySymbol, Element, Level, StructuralType If it is to be hosted on a wall, floor or ceiling and associated to a reference level
XYZ, FamilySymbol, Level, StructuralType If it is to be associated to a reference level
Face, XYZ, XYZ, FamilySymbol If it is face-based and needs to be oriented in a non-default direction
Reference, XYZ, XYZ, FamilySymbol If it is face-based and needs to be oriented in a non-default direction, accepts a reference to a face rather than a Face
Face, Line, FamilySymbol If it is face-based and linear
Reference, Line, FamilySymbol If it is face-based and linear, but accepts a reference to a face, rather than a Face

Columns

Structural Columns

XYZ, FamilySymbol, Level, StructuralType Creates the column so that its base lies on the reference level. The column will extend to the next available level in the model, or will extend the default column height if there are no suitable levels above the reference level.

Doors

Windows

XYZ, FamilySymbol, Element, StructuralType Doors and windows must be hosted by a wall. Use this method if they can be placed with the default orientation.
XYZ, FamilySymbol, XYZ, Element, StructuralType If the created instance needs to be oriented in a non-default direction
XYZ, FamilySymbol, Element, Level, StructuralType If the instance needs to be associated to a reference level
Structural Framing (Beams, Braces) Curve, FamilySymbol, Level, StructuralType Creates a level based brace or beam given its curve. This is the recommended method to create Beams and Braces
XYZ, FamilySymbol, StructuralType Creates instance in an arbitrary location1
XYZ, FamilySymbol, Element, Level, StructuralType If it is hosted on an element (floor etc.) and associated to a reference level1
XYZ, FamilySymbol, Level, StructuralType If it is associated to a reference level1
XYZ, FamilySymbol, Element, StructuralType If it is hosted on an element (floor etc.)1
Detail Component Line, FamilySymbol, View Applies only to 2D family line based detail symbols
Generic Annotations XYZ, FamilySymbol, View Applies only to 2D family symbols

1 The structural instance will be of zero-length after creation. Extend it by setting its curve (FamilyInstance.Location as LocationCurve) using LocationCurve.Curve property.

You can simplify your code and improve performance by creating more than one family instance at a time using Document.NewFamilyInstances(). This method has a single parameter, which is a list of FamilyInstanceCreationData objects describing the family instances to create.

Code Region 12-2: Batch creating family instances

ICollection<ElementId> BatchCreateColumns(Autodesk.Revit.DB.Document document, Level level)
{
        List<FamilyInstanceCreationData> fiCreationDatas = new List<FamilyInstanceCreationData>();
        
        ICollection<ElementId> elementSet = null;
        
        //Try to get a FamilySymbol
        FamilySymbol familySymbol = null;
        FilteredElementCollector collector = new FilteredElementCollector(document);
        ICollection<Element> collection = collector.OfClass(typeof(FamilySymbol)).ToElements();
        foreach (Element e in collection)
        {
                familySymbol = e as FamilySymbol;
                if (null != familySymbol.Category)
                {
                        if ("Structural Columns" == familySymbol.Category.Name)
                        {
                                break;
                        }
                }
        }

        if (null != familySymbol)
        {
                //Create 10 FamilyInstanceCreationData items for batch creation 
                for (int i = 1; i < 11; i++)
                {
                        XYZ location = new XYZ(i * 10, 100, 0);
                        FamilyInstanceCreationData fiCreationData = new FamilyInstanceCreationData(location, familySymbol, level, 
                                        StructuralType.Column);
                        if (null != fiCreationData)
                        {
                                fiCreationDatas.Add(fiCreationData);
                        }
                }
                
                if (fiCreationDatas.Count > 0)
        {
                        // Create Columns
            elementSet = document.Create.NewFamilyInstances2(fiCreationDatas);
        }
                else
                {
                throw new Exception("Batch creation failed.");
                }
    }
        else
        {
                throw new Exception("No column types found.");
        }
        
        return elementSet;
}

Instances of some family types are better created through methods other than Autodesk.Revit.Creation.Document.NewFamilyInstance(). These are listed in the table below.

Table 33 - Options for creating instances with other methods

Category

Creation method

Comments

Air Terminal Tags

Area Load Tags

Area Tags

Casework Tags

Ceiling Tags

Communication Device Tags

Curtain Panel Tags

Data Device Tags

Detail Item Tags

Door Tags

Duct Accessory Tags

Duct Fitting Tags

Duct Tags

Electrical Equipment Tags

Electrical Fixture Tags

Fire Alarm Device Tags

Flex Duct Tags

Flex Pipe Tags

Floor Tags

Furniture System Tags

Furniture Tags

Generic Model Tags

Internal Area Load Tags

Internal Line Load Tags

Internal Point Load Tags

Keynote Tags

Lighting Device Tags

Lighting Fixture Tags

Line Load Tags

Mass Floor Tags

Mass Tags

Mechanical Equipment Tags

Nurse Call Device Tags

Parking Tags

Pipe Accessory Tags

Pipe Fitting Tags

Pipe Tags

Planting Tags

Plumbing Fixture Tags

Point Load Tags

Property Line Segment Tags

Property Tags

Railing Tags

Revision Cloud Tags

Roof Tags

Room Tags

Security Device Tags

Site Tags

Space Tags

Specialty Equipment Tags

Spinkler Tags

Stair Tags

Structural Area Reinforcement Tags

Structural Beam System Tags

Structural Column Tags

Structural Connection Tags

Structural Foundation Tags

Structural Framing Tags

Structural Path Reinforcement Tags

Structural Rebar Tags

Structural Stiffener Tags

Structural Truss Tags

Telephone Device Tags

Wall Tags

Window Tags

Wire Tag

Zone Tags

NewTag(View, Element, Boolean, TagMode, TagOrientation, XYZ)

TagMode should be TM_ADDBY_CATEGORY and there should be a related tag family loaded when try to create a tag, otherwise exception will be thrown

Material Tags

NewTag(View, Element, Boolean, TagMode, TagOrientation, XYZ)

TagMode should be TM_ADDBY_MATERIAL and there should be a material tag family loaded, otherwise exception will be thrown

Multi-Category Tags

NewTag(View, Element, Boolean, TagMode, TagOrientation, XYZ)

TagMode should be TM_ADDBY_MULTICATEGORY, and there should be a multi-category tag family loaded, otherwise exception will be thrown

Title Blocks

ViewSheet.Create(Document, ElementId)

The titleblock will be added to the newly created sheet.

Families and family symbols are loaded using the Document.LoadFamily() or Document.LoadFamilySymbol() methods. Some families, such as Beams, have more than one endpoint and are inserted in the same way as a single point instance. Once the linear family instances are inserted, their endpoints can be changed using the Element.Location property. For more information, refer to Code Samples.