Families, Symbols, Instances & System Families

In this article I will present some means of getting families, instances, symbols and system family objects using the Revit collector.

Family Structure

But let’s start with the basics, because like many others when I first started I was a bit confused on the differences between these concepts.

So what is a family? According to the Autodesk Knowledge site it is “a group of elements with a common set of properties, called parameters, and a related graphical representation”.  A proper classification and description can be found following this link

So in Revit there are 2 types of families (Component Families and System Families). The component families are the families that the user can create and load and the system families are built-in, the user can only create derived types.

Following the documentation, in Revit custom families are represented in full by:

• Family – the entire family that consists of a collection of types
• FamilySymbol – The collection of types that the family contains.
• FamilyInstance – actual instance of that type in the revit model

Type vs Symbol

So there is a lot of confusion between the FamilySymbol and the FamilyType, and I was all the same confused when I first dove in the api of Revit. For a detailed explanation you can follow Jeremy’s article here.

There are 2 contexts in which a Type exists, one is in the Revit Model space and another one is in the Revit Family Editor. For this exact reason there are 2 classes, because they represent the same thing but are different objects. One belongs to the family, the other exists when it’s loaded in the model space.

• The family type is what the Family object actually contains, it’s the object that actually defines the type will all of the parameters and so on.
• The family symbol exists when the family type is loaded in the Revit Model space. It’s a compiled FamilyType with limited operations allowed on it, because it’s definition is made inside the Editor.

You can only get types in the Family Editor

Definitions:

• Family :
  • A virtual representation of a working item that has a specific set of conceptual characteristics, and that can be configured in many ways using the defined parameters.
  • As an example a family can be a round table where it’s diameter can be configured dynamically
• Family Type
  • A family can have multiple types that inherit the families characteristics, but will fix some parameter values for that type’s resolution.
  • As an example a family type can be round table of 3 meters , it derives from the family therefore it’s round, but it has the diameter fixed. Other configurations can be applied if there are instance parameters defined
• FamilySymbol
  • A family symbol is the Revit api class name that in the UI it’s called a type.
  • A family symbol is the same as the type, only that the type is the actual definition and it belongs to the family. The symbol is the compiled type in the model space.
• A system family
  • Built in families that are not available for creating. Revit provides the graphical representation and you can only create derived types. They are walls, dimensions, etc.
  • A system family type in revitapi is the HostObjAttributes class and the instance is the HostObject class

To read more about this, please visit the following link.

For getting instances of the Component Family, we can query for the FamilyInstance type. System families are different, they actually have dedicated classes (like Wall, Dimension). We can query for these typed classed if we know that we want them. All system family instances can be retrieved by querying for their parent class HostObject

Getting family instances and system family type instances

List allInstances = new FilteredElementCollector(document)
           .OfClass(typeof(FamilyInstance))
           .OfType()
           .ToList();

List wallInstances = new FilteredElementCollector(document)
           .OfClass(typeof(Wall))
           .OfType()
           .ToList();

List systemFamilyInstances = new FilteredElementCollector(document)
           .OfClass(typeof(HostObject))
           .OfType()
           .ToList();

Getting families

 List allInstances = new FilteredElementCollector(document)
        .OfClass(typeof(FamilyInstance))
        .OfType()
        .ToList();

Getting system family types

 var systemTypes = new FilteredElementCollector(document)
        .OfClass(typeof(HostObjAttributes))
        .ToList();

Getting a specific family symbol

  FamilySymbol mullionSymbol = new FilteredElementCollector(document)
        .OfClass(typeof(FamilySymbol))
        .OfType()
        .Where(x => x.FamilyName == "Rectangular Mullion" && x.Name == "64 x 128 rectangular")
        .FirstOrDefault();

Getting all symbols of a family with a filter

 List allMullionSymbols = new FilteredElementCollector(document)
        .WherePasses(new FamilySymbolFilter(mullionSymbol.Family.Id))
        .OfType()
        .ToList();

Getting all instances for a symbol

 var mullionInstances = new FilteredElementCollector(document)
        .WherePasses(new FamilyInstanceFilter(document, mullionSymbol.Id))
        .OfType()
        .ToList();

Everything is accessible

 //Just getting the first mullion with this type name
FamilyInstance aRandomMullion = allInstances.Where(x => x.Name == "64 x 128 rectangular").FirstOrDefault();
//the family is accessed via the symbol of the family
Family mullionFamily = aRandomMullion.Symbol.Family;

string name = document.FamilyManager.CurrentType.Name;

FamilyTypeSet types = document.FamilyManager.Types;