RevitPythonShell: Families

<<< Return to Nathan's Revit API Notebook

Introduction

This section provides examples for creating and adjusting family parameters, placing family instances, and modifying instance parameters using the Revit API.

Family Parameters

When we are creating a new family get parameter values, and set parameters to new values. Most of the work will be done using FamilyManager.Parameters

Getting a Parameter

We can get a parameter value by using FamilyManager.CurrentType.AsDouble()

The following code uses a simple box family with parameters for 'height', 'length', and 'width.' The code will print the values of each parameter to the console.

import clr
clr.AddReference('RevitAPI') 
clr.AddReference('RevitAPIUI') 
from Autodesk.Revit.DB import * 
 
app = __revit__.Application
doc = __revit__.ActiveUIDocument.Document
 
t = Transaction(doc, 'Print family parameters')
 
t.Start()
 
#define parameter variables
height = [a for a in doc.FamilyManager.Parameters if a.Definition.Name=='height'][0]
length = [a for a in doc.FamilyManager.Parameters if a.Definition.Name=='length'][0]
width = [a for a in doc.FamilyManager.Parameters if a.Definition.Name=='width'][0]
 
#get parameter values
hvalue = doc.FamilyManager.CurrentType.AsDouble(height)
lvalue = doc.FamilyManager.CurrentType.AsDouble(length)
wvalue = doc.FamilyManager.CurrentType.AsDouble(width)
 
#print parameter values
print 'Height = ' + str(hvalue)
print 'Length = ' + str(lvalue)
print 'Width = ' + str(wvalue)
 
t.Commit()

Setting a Parameter

We can get a parameter value by using FamilyManager.Set(). The following code will set parameters for 'height', 'length', and 'width.

import clr
clr.AddReference('RevitAPI') 
clr.AddReference('RevitAPIUI') 
from Autodesk.Revit.DB import * 
 
app = __revit__.Application
doc = __revit__.ActiveUIDocument.Document
 
t = Transaction(doc, 'Set family parameters')
 
t.Start()
 
#define parameter variables
height = [a for a in doc.FamilyManager.Parameters if a.Definition.Name=='height'][0]
length = [a for a in doc.FamilyManager.Parameters if a.Definition.Name=='length'][0]
width = [a for a in doc.FamilyManager.Parameters if a.Definition.Name=='width'][0]
 
#set parameters
doc.FamilyManager.Set(height, 100)
doc.FamilyManager.Set(length, 25)
doc.FamilyManager.Set(width, 50)
 
t.Commit()
 
__window__.Close()

Increment a Parameter

We can combine getting and setting techniques to increment the current parameter by some value. The following take the existing parameter values in the document and adds '10'.

import clr
import math
clr.AddReference('RevitAPI') 
clr.AddReference('RevitAPIUI') 
from Autodesk.Revit.DB import * 
 
app = __revit__.Application
doc = __revit__.ActiveUIDocument.Document
 
t = Transaction(doc, 'Increment family parameters')
 
t.Start()
 
#define parameter variables
height = [a for a in doc.FamilyManager.Parameters if a.Definition.Name=='height'][0]
length = [a for a in doc.FamilyManager.Parameters if a.Definition.Name=='length'][0]
width = [a for a in doc.FamilyManager.Parameters if a.Definition.Name=='width'][0]
 
#get current values
hvalue = doc.FamilyManager.CurrentType.AsDouble(height)
lvalue = doc.FamilyManager.CurrentType.AsDouble(length)
wvalue = doc.FamilyManager.CurrentType.AsDouble(width)
 
#set new values
doc.FamilyManager.Set(height, hvalue + 10)
doc.FamilyManager.Set(length, lvalue + 10)
doc.FamilyManager.Set(width, wvalue + 10)
 
t.Commit()
 
__window__.Close()

Family Instances

Placing a Single Family Instance

Family instances can be placed using FamilyCreate.NewFamilyInstance()

This code will place an instance of 'BoxFamily' at location 0,0,0 in the document.

import clr
clr.AddReference('RevitAPI') 
clr.AddReference('RevitAPIUI') 
from Autodesk.Revit.DB import * 
 
app = __revit__.Application
doc = __revit__.ActiveUIDocument.Document
 
t = Transaction(doc, 'Create family instance.')
 
t.Start()
 
#Family symbol name to place.
symbName = 'BoxFamily'
 
#create a filtered element collector set to Category OST_Mass and Class FamilySymbol 
collector = FilteredElementCollector(doc)
collector.OfCategory(BuiltInCategory.OST_Mass)
collector.OfClass(FamilySymbol)
 
famtypeitr = collector.GetElementIdIterator()
famtypeitr.Reset()
 
#Search Family Symbols in document.
for item in famtypeitr:
    famtypeID = item
    famsymb = doc.get_Element(famtypeID)
 
    #If the FamilySymbol is the name we are looking for, create a new instance.
    if famsymb.Family.Name == symbName:
 
        #location to place family
        loc = XYZ(0,0,0) 
 
        #NewFamilyInstance()
        familyInst = doc.FamilyCreate.NewFamilyInstance(loc, famsymb, Structure.StructuralType.NonStructural)
 
t.Commit()
 
__window__.Close()

Placing Multiple Family Instances

We can place a grid of family instances by using a loop to change the XYZ insertion point.

import clr
clr.AddReference('RevitAPI') 
clr.AddReference('RevitAPIUI') 
from Autodesk.Revit.DB import * 
 
app = __revit__.Application
doc = __revit__.ActiveUIDocument.Document
 
t = Transaction(doc, 'Create multiple family instances.')
 
t.Start()
 
symbName = 'BoxFamily'
 
collector = FilteredElementCollector(doc)
collector.OfCategory(BuiltInCategory.OST_Mass)
collector.OfClass(FamilySymbol)
 
famtypeitr = collector.GetElementIdIterator()
famtypeitr.Reset()
 
for item in famtypeitr:
    famtypeID = item
    famsymb = doc.get_Element(famtypeID)
 
    if famsymb.Family.Name == symbName:
 
        #Use nested for loop to create grid of family instances.
        for i in range(0,10):
            for j in range(0,10):
 
                loc = XYZ((i*70),(j*70),0) 
                familyInst = doc.FamilyCreate.NewFamilyInstance(loc, famsymb, Structure.StructuralType.NonStructural)
 
t.Commit()
 
__window__.Close()

Instance Parameters

We can modify the parameters of Family Instances using FamilyInstance.get_Parameter()

Setting Parameters of Existing Instances

We can modify the parameters of Family Instances already in the scene by filtering for the Family Instances and then using get_Parameter to change a value.

This example increments a value called 'inc' to set the BoxFamily instances from the previous example to different heights.

import clr
clr.AddReference('RevitAPI') 
clr.AddReference('RevitAPIUI') 
from Autodesk.Revit.DB import * 
 
app = __revit__.Application
doc = __revit__.ActiveUIDocument.Document
 
t = Transaction(doc, 'Modify existing family instances.')
 
t.Start()
 
instName = 'BoxFamily'
 
collector = FilteredElementCollector(doc)
collector.OfCategory(BuiltInCategory.OST_Mass)
collector.OfClass(FamilyInstance)
 
famtypeitr = collector.GetElementIdIterator()
famtypeitr.Reset()
 
inc = 1
 
for item in famtypeitr:
    famtypeID = item
    faminst = doc.get_Element(famtypeID)
 
    if faminst.Name == instName:
        param = faminst.get_Parameter('height')
        param.Set(2*inc)
        inc = inc + 1
 
t.Commit()
 
__window__.Close()

Setting Parameters when Creating Instances

We can also set the parameters of Family Instances while creating them. This example uses the i and j values of a 4 loop to control a the height of the BoxFamily.

Note: This example will take time to generate. Be patient!

import clr
import math
clr.AddReference('RevitAPI') 
clr.AddReference('RevitAPIUI') 
from Autodesk.Revit.DB import * 
 
app = __revit__.Application
doc = __revit__.ActiveUIDocument.Document
 
t = Transaction(doc, 'Create multiple family instances.')
 
t.Start()
 
symbName = 'BoxFamily'
 
collector = FilteredElementCollector(doc)
collector.OfCategory(BuiltInCategory.OST_Mass)
collector.OfClass(FamilySymbol)
 
famtypeitr = collector.GetElementIdIterator()
famtypeitr.Reset()
 
for item in famtypeitr:
    famtypeID = item
    famsymb = doc.get_Element(famtypeID)
 
    if famsymb.Family.Name == symbName:
 
        for i in range(0,20):
            for j in range(0,20):
 
                loc = XYZ((i*70),(j*70),0) 
                familyInst = doc.FamilyCreate.NewFamilyInstance(loc, famsymb, Structure.StructuralType.NonStructural)
 
                #modify FamilyInstance parameter using i and j values
                h = abs((60 * math.sin(i))+(60* math.cos(j))) + 10
                param = familyInst.get_Parameter('height')
                param.Set(h)
 
t.Commit()
 
__window__.Close()