FamilyInstances

Examples of categories of FamilyInstance objects in Revit are Beams, Braces, Columns, Furniture, Massing, and so on. 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);
    }
}

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.

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 location₁
	XYZ, FamilySymbol, Element, Level, StructuralType	If it is hosted on an element (floor etc.) and associated to a reference level₁
	XYZ, FamilySymbol, Level, StructuralType	If it is associated to a reference level₁
	XYZ, FamilySymbol, Element, StructuralType	If it is hosted on an element (floor etc.)₁
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

₁ 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	NewViewSheet(FamilySymbol)	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.