3 Revit Family API

Revit Family API
Developer Technical Services
© 2013 Autodesk The Revit Family API

Revit Family API
Background
 Family content creation itself is highly customizable feature even
without API
 Understanding how it works in UI is a key to successful creation in API
 There used to be two Revit API expertise communities
 those who know UI and content creation well
 those who are fluent in programming, but are not familiar with UI
Goals of this talk

 Learn the Family API along the best practice in UI
 Establish steps to follow to write a program using Family API, which
are stable, flexible and adaptable when you move beyond the basics

Agenda
Revit Family from UI

 What is it?
 Where to begin, flavors, editor, what is possible
 Best practice
Family creation using API
 Learning along best practice
 Example: L-shape column
 Learning resources

Revit Families – What is it?
Graphic representations of building objects and symbols
 Geometry in 3D or 2D
 Data that supports definition/creation of objects
Generically - 3 Types
 System Families – stored in the project template
 Walls, Roofs, Floors, Ceilings…
 In-Place Families – “one of kind objects”
 Standard Families – freestanding “.rfa” files
 Windows, Doors, Furniture, Beams, Light Fixtures…
 API in 2010

Revit Families – Where to begin
Which is better?
 Start from a family template
 Modify an existing family
Which Family template to start with?
 2D or 3D, model or detail component
 Hosted or non hosted: Wall, Ceiling,
Face based…
 Category
 Placement type: free or 2 point
 Specialty: Truss, Rebar…

Revit Family Flavors
Revit Architecture
 Basic building components with simplistic interactions in the model
 Free placement objects - casework, furniture, etc.
 “2 point” placement objects – beams, detail components, etc.
 Hosted objects: windows, doors, columns (“level to level”), ceiling or “wall
based” lighting fixtures
Revit Structure
 Additional components with complex interactions with other objects
 Framing - beams (“beams to beam”, “beam to column”), columns
 Trusses - layout for girder trusses; Boundary Conditions
 Span Direction Symbols; Reinforcement Symbols - area reinforcement
expands to find edges, path reinforcement
Revit MEP
 Connectors allowing objects to resize based on what they are connected to

Revit Family Editor
Revit offers 6 basic family editors

 3D model, annotation, detail, rebar, truss and conceptual mass.
Each family editor provides a specific set and is tied to the

chosen family template
 Geometry – extrusions, blends, sweeps, revolves, swept blends
 Lines – model, symbolic, detail
 Basic tools – copy, mirror, paint, join/unjoin, cut geometry/don’t cut
 References – reference planes, reference lines
 Annotation tools – labels
 Advanced tools – formulas, nesting, arrays, type catalogs
 MEP tools – add connectors

Revit Families Best Practice
The “process” for building families is the most important aspect of
family creation that one needs to learn
Process order:
1. Plan (Insertion Point, Parametric Origin)
2. Layout Reference Planes (The Bones)
3. Add Parameters
4. Add multiple host thickness types (for testing hosted families)
5. Add 2 or more types
6. Flex Types and Host (Testing Procedure)
7. Add a Single Level of Geometry
8. Repeat Steps 6 and 7 until you are satisfied with the results
9. Test in Project Environment (create testing project)
Steven Campbell, Revit Content Project Manager

Revit Families – What is possible
 Formulas – can be used to control behaviour, visibility, arrays

 Arrays and nesting – repeatable, resizable elements across an array
 Advanced nesting – subcomponents can be swapped

 Reference lines – angular movement

Family Resources
 Revit Families Guide
 2009 & 2010 release
 Newsgroups
 discussion.autodesk.com
 AUGI - http://forums.augi.com
 Books & DVD’s
 Mastering Autodesk Revit Building – Paul F. Aubin
 Mastering Family Editor Series - 5 DVD’s – Paul F. Aubin
 Learning Autodesk Revit MEP 2012 video training by Simon
Whitbread, Don Bokmiller and Joel Londenberg
http://cad-notes.com/2011/12/learning-autodesk-revit-mep-2012-training-video-is-available

Family API
Learn basics along the best practice

Family API Overview
What is it?
Revit API within the family editor context

Automate library generation, generate a family library on the fly,
possibly linking with other library specification
Extract information and modify
Analogous to UI
There are a few differences and limitations you may want to be
aware

Family API Overview
Family specific classes and methods
FamilyManager class:
 add/remove/rename types, add/remove parameters, set values and
formulas
Document methods specific to family context:
 IsFamilyDocument – identifies whether the current document is a family document
 OwnerFamily – returns the owning family of this family document
 FamilyManager – returns a FamilyManager object to provide access to family
types and parameters
 FamilyCreate – returns a FamilyItemCreate object to create new instances of
elements within a family document, analogous to the Create object in a project
 EditFamily – edit a family loaded in a project document

Labs Exercises
Hands-on

Family API Labs Exercises
Hands-on
Incremental exercises to create a column family:
Lab1 – create a column family with rectangular profile

Lab2 – create a column family with L-shaped profile
Lab3 – add formula and assign materials
Lab4 – add visibility control
Include step-by-step instruction

In VB.NET and C#

Lab1 – Create a Rectangular Column
Objective: learn THE basics of family API.

 check the family context
 create a simple solid using extrusion
 set alignments
 add types
Classes and methods:

 rvtDoc.IsFamilyDocument()
 rvtDoc.OwnerFamily.FamilyCategory.Name
 rvtDoc.FamilyCreate.NewExtrusion()
 rvtDoc.FamilyCreate.NewAlignment()
 familyMgr = rvtDoc.FamilyManager
 familyMgr.NewType()
 familyMgr.Parameter(); familyMgr.Set()

Lab2 – Create a L-Shape Column
Objective: learn the basics of family API.

 add reference planes
 add parameters
 add dimensions

 rvtDoc.FamilyCreate.NewReferencePlane()
 familyMgr.AddParameter()
 rvtDoc.FamilyCreate.NewDimension()

Lab3 – Add Formulas and Materials
Objective: learn the basics of family API.

 add formulas
 add materials

 familyMgr.SetFormula()
 pSolid.Parameter(“Material”)
 familyMgr.AddParameter(“MyColumnFinish”,
BuiltInParameterGroup.PG_MATERIALS, ParameterType.Material, True)
 familyMgr.AssociateElementParameterToFamilyParameter()

Lab4 – Add Visibility Control
Objective:
 add line representation
 add visibility control

 rvtDoc.FamilyCreate.NewSymbolicCurve()
 rvtDoc.FamilyCreate.NewModelCurve()
 FamilyElementVisibility(FamilyElementVisibilityType.ViewSpecific/Model)
 FamilyElementVisibility.IsShownInFine, etc.
 pLine.SetVisibility(pFamilyElementVisibility)

Family API along Best Practice
Example: Simple L-shape column
Reference planes
Parameters  Plan
Dimensions  Reference planes
Types  Parameters
Geometry  Types
Alignments  Geometry

1. Plan
Right template (e.g., “Metric Column.rft”)

Understand your template
Upper Ref Level
Center (Left/Right)
Left Right
Back
Center (Front/Back)
Front
Lower Ref. Level
Reference Plane

1. Plan
Validate the document
Function ValidateDocument(ByVal rvtDoc As Document) As Boolean

'' our command works in the context of family editor only
If Not rvtDoc.IsFamilyDocument Then
TaskDialog.Show("Family API", "This works only in the family editor.")
Return False
Check if the current
End If
document is a family
'' check if we have a right template
document
Dim ownerFamily As Family = rvtDoc.OwnerFamily
If ownerFamily Is Nothing Then
TaskDialog.Show("Family API", "This document does not have Owner Family.")
Return False
End If Get the Family of
'' check the family category of this document this document
Dim catColumn As Category = _
rvtDoc.Settings.Categories.Item(BuiltInCategory.OST_Columns)
If Not ownerFamily.FamilyCategory.Id.Equals(catColumn.Id) Then
TaskDialog.Show("Family API", "Please open Metric Column.rft")
End If
Return True Check the family
End Function category of this
document
2. Layout Reference Planes
Add reference planes
Reference Plane :
OffsetV
Reference Plane :
OffsetH

Example: Vertical offset
Sub AddReferencePlane_VerticalOffset()
'' create a reference plan, using NewReferencePlane
Dim pt1 As New XYZ(-0.5, -2.0, 0.0) '' one end
Dim pt2 As New XYZ(-0.5, 2.0, 0.0) '' the other end
Dim vec As XYZ = XYZ.BasisZ '' perpendicular to the first line.
Dim view As View = _
Utils.FindElement(rvtDoc, GetType(ViewPlan), "Lower Ref. Level")
Dim refPlane As ReferencePlane = _

m_rvtDoc.FamilyCreate.NewReferencePlane(pt1, pt2, vec, view)
refPlane.Name = "OffsetV"
End Sub

Example: Vertical offset
Sub AddReferencePlane_VerticalOffset()
Dim vec As XYZ = XYZ.BasisZ '' perpendicular to the first line.
Dim refPlane As ReferencePlane = _ z

m_rvtDoc.FamilyCreate.NewReferencePlane(pt1, pt2, vec, view)
End Sub
z (0,0,1)
y
pt1 pt2
x
Example: NewReferencePlane2()
Sub AddReferencePlane_VerticalOffset2()
Dim pt3 As New XYZ(-0.5, -1.0, 1.0) '' the third point
Dim refPlane As ReferencePlane = _ z

m_rvtDoc.FamilyCreate.NewReferencePlane2(pt1, pt2, pt3, view)
End Sub
pt3
pt1 pt2
x
3. Add Parameters
Parameters
Dimensions

3a. Add Parameters
Example: Tw
Dim m_familyMgr As FamilyManager = m_rvtDoc.FamilyManager
Sub AddParameter_Tw()
'' add a parameter "Tw"
Dim isInstance As Boolean = False
Dim paramTw As FamilyParameter = _ m_familyMgr.AddParameter( _
"Tw", BuiltInParameterGroup.PG_GEOMETRY, ParameterType.Length, isInstance)
'' give initial values.
Dim tw As Double = Utils.mmToFeet(150.0) '' in metric
'Dim tw As Double = 0.5 '' in feet
m_familyMgr.Set(paramTw, tw)
'' add a formula (optional)
m_familyMgr.SetFormula( _
paramTw, "Width / 4.0“)
End Sub

3a. Add Parameters
Example: Column Finish
Sub AddParameter_Material()
'' add a parameter "Tw"

Dim param As FamilyParameter = m_familyMgr.AddParameter("Column Finish", _
BuiltInParameterGroup.PG_MATERIALS, ParameterType.Material, True)
'' we will come back to setting to a solid later

End Sub

3b Add Dimensions
Example: Tw
Sub AddDimention_Tw()
'' find the plan view that we want to place a dimension
Dim pViewPlan As View = _
Utils.FindElement(m_rvtDoc, GetType(ViewPlan), "Lower Ref. Level")
'' find two reference planes which we want to add a dimension between
Dim ref1 As ReferencePlane = _
Utils.FindElement(m_rvtDoc, GetType(ReferencePlane), "Left")
Dim ref2 As ReferencePlane = _
Utils.FindElement(m_rvtDoc, GetType(ReferencePlane), "OffsetV")
'' make an array of references
Dim pRefArray As New ReferenceArray
pRefArray.Append(ref1.Reference)
pRefArray.Append(ref2.Reference)
'' define a dimension line
Dim p0 As XYZ = ref1.FreeEnd
Dim p1 As XYZ = ref2.FreeEnd
Dim pLine As Line = Line.CreateBound(p0, p1)
'' create a dimension
Dim pDimTw As Dimension = _
m_rvtDoc.FamilyCreate.NewDimension(pViewPlan, pLine, pRefArray)
'' add label to the dimension
pDimTw.Label = m_familyMgr.Parameter("Tw")
End Sub
4. Add Multiple Host Thickness Types
For testing purposes

No host in our example.

5. Add Two or More Types

5. Add Two or More Types
Example: Width x Depth
Sub AddType(ByVal name As String, ByVal w As Double, ByVal d As Double)
'' add new types with the given name.
Dim type1 As FamilyType = m_familyMgr.NewType(name)
'' look for 'Width' and 'Depth' parameters and set them with the given values
Dim paramW As FamilyParameter = m_familyMgr.Parameter("Width")
Dim valW As Double = Utils.mmToFeet(w)
If paramW IsNot Nothing Then
m_familyMgr.Set(paramW, valW)
End If
Dim paramD As FamilyParameter = m_familyMgr.Parameter("Depth")
Dim valD As Double = Utils.mmToFeet(d)
If paramD IsNot Nothing Then
m_familyMgr.Set(paramD, valD)
End If
End Sub
Sub AddTypes()
'' AddType(name,Width,Depth)
AddType("600x900", 600.0, 900.0)
AddType("1000x300", 1000.0, 300.0)
AddType("600x600", 600.0, 600.0)
End Sub

Testing Procedure

7. Add Single Level of Geometry
Add a solid
Add alignments

7a. Add Single Level of Geometry
Example: Extrusion
Function CreateSolid() As Extrusion

'' (1) define a simple L-shape profile
Dim pProfile As CurveArrArray = CreateProfileLShape()
'' (2) create a sketch plane

Dim pRefPlane As ReferencePlane = _
Utils.FindElement(m_rvtDoc, GetType(ReferencePlane), "Reference Plane")
Dim pSketchPlane As SketchPlane = _
SketchPlane.Create(m_rvtDoc, pRefPlane.Plane)
'' (3) height of the extrusion. distance between Lower and Upper Ref Level.
Dim dHeight As Double = Utils.mmToFeet(4000)
'' (4) create an extrusion here. at this point.

Dim bIsSolid As Boolean = True '' as oppose to void.
Dim pSolid As Extrusion = _
m_rvtDoc.FamilyCreate.NewExtrusion(bIsSolid, pProfile, pSketchPlane,
dHeight)
Return pSolid
End Function

tw
7a. Add Single Level of Geometry 5 4
Example: L-shape profile
Function CreateProfileLShape() As CurveArrArray
d O
Dim w As Double = Utils.mmToFeet(600) 3 2
Dim d As Double = Utils.mmToFeet(600) td
Dim tw As Double = Utils.mmToFeet(150) 0 1
Dim td As Double = Utils.mmToFeet(150)
w
'' define vertices (the last one is to make the loop simple)
Const nVerts As Integer = 6 '' the number of vertices
Dim pts() As XYZ = {New XYZ(-w / 2, -d / 2, 0), New XYZ(w / 2, -d / 2, 0), _
New XYZ(w / 2, -d / 2 + td, 0), New XYZ(-w / 2 + tw, -d / 2 + td, 0), _
New XYZ(-w / 2 + tw, d / 2, 0), New XYZ(-w / 2, d / 2, 0), _
New XYZ(-w / 2, -d / 2, 0)}
'' define a loop. define individual edges and put them in a curveArray
Dim pLoop As CurveArray = m_rvtApp.Create.NewCurveArray
Dim lines(nVerts - 1) As Line
For i As Integer = 0 To nVerts - 1
lines(i) = Line.CreateBound(pts(i), pts(i + 1))
pLoop.Append(lines(i))
Next
'' then, put the loop in the curveArrArray as a profile
Dim pProfile As CurveArrArray = m_rvtApp.Create.NewCurveArrArray
pProfile.Append(pLoop)
Return pProfile
End Function
7b. Add Alignments
Example: lock a face on the ref plane “OffsetV”
Sub AddAlignment_ReferencePlane(ByVal pSolid As Extrusion, _

ByVal normal As XYZ, ByVal nameRefPlane As String)

'' get the plan view
Dim pViewPlan As View = _
Utils.FindElement(m_rvtDoc, GetType(ViewPlan), "Lower Ref. Level")

'' find reference planes
Dim refPlane As ReferencePlane = _
Utils.FindElement(m_rvtDoc, GetType(ReferencePlane), nameRefPlane)

'' find the face of the solid
Dim pFace As PlanarFace = Utils.FindFace(pSolid, normal, refPlane)

'' create a locked alignment
m_rvtDoc.FamilyCreate.NewAlignment( _
pViewPlan, refPlane.Reference, pFace.Reference)

End Sub

7b. Add Alignments
Example: Level alignment
Sub AddAlignment_Level( _
ByVal pSolid As Extrusion, ByVal normal As XYZ, ByVal nameLevel As String)

'' which direction are we looking at?
Dim pView As View = Utils.FindElement(m_rvtDoc, GetType(View), "Front")

'' find the upper ref level. FindElement() is a helper function.
Dim pLevel As Level = Utils.FindElement(m_rvtDoc, GetType(Level), nameLevel)

'' find the face of the box. FindFace() is a helper function.
Dim pFace As PlanarFace = Utils.FindFace(pSolid, normal)

'' create alignments
m_rvtDoc.FamilyCreate.NewAlignment(pView, pLevel.PlaneReference,
pFace.Reference)

End Sub

7b. Add Alignments
Example: L-shape solid alignments
Sub AddAlignments(ByVal pSolid As Extrusion)

AddAlignment_Level(pSolid, New XYZ(0.0, 0.0, 1.0), "Upper Ref Level")
AddAlignment_Level(pSolid, New XYZ(0.0, 0.0, -1.0), "Lower Ref. Level")
AddAlignment_ReferencePlane(pSolid, New XYZ(1.0, 0.0, 0.0), "Right")
AddAlignment_ReferencePlane(pSolid, New XYZ(-1.0, 0.0, 0.0), "Left")
AddAlignment_ReferencePlane(pSolid, New XYZ(0.0, -1.0, 0.0), "Front")
AddAlignment_ReferencePlane(pSolid, New XYZ(0.0, 1.0, 0.0), "Back")
AddAlignment_ReferencePlane(pSolid, New XYZ(1.0, 0.0, 0.0), "OffsetV")
AddAlignment_ReferencePlane(pSolid, New XYZ(0.0, 1.0, 0.0), "OffsetH")

End Sub

8. Repeat Steps 6 and 7 Till Satisfied

7. Add geometry

9. Test in Project Environment
Create Testing Project

Additional Classes and Methods
Visibility
Sub SetVisibility(ByVal pSolid As Extrusion)

'' set the visibility of the model not to shown in coarse.
Dim pVis As FamilyElementVisibility = _
New FamilyElementVisibility(FamilyElementVisibilityType.Model)
pVis.IsShownInCoarse = False

pSolid.SetVisibility(pVis)
End Sub

Additional Classes and Methods
Associate parameters
Sub addMaterials(ByVal pSolid As Extrusion)

'' get the material id that we are intersted in (e.g., "Glass")
Dim pMat As Material = Utils.FindElement(m_rvtDoc, GetType(Material), "Glass")
Dim idMat As ElementId = pMat.Id
'' add a parameter for material finish
Dim paramFamilyMaterial As FamilyParameter = _
m_familyMgr.Parameter("Column Finish")

'' associate material parameter to the family parameter we just added
Dim paramSolidMaterial As Parameter = pSolid.Parameter("Material")
m_familyMgr.AssociateElementParameterToFamilyParameter( _
paramSolidMaterial, paramFamilyMaterial)

'' let's add another type with Glass finish
AddType("Glass", 600.0, 600.0)
m_familyMgr.Set(paramFamilyMaterial, idMat)
End Sub

Family API SDK Samples
For further references

Family API SDK Samples
Learning resources
In <SDK folder>\Samples\FamilyCreation
AutoJoin
 Automatically join geometry of multiple generic forms for use in family modeling and massing
 Uses the method Document::CombineElements to join geometry between overlapping generic forms
 Provide a utility method check geometry object overlap, based on Face::Intersect(Curve) method
AutoParameter
 Batch mode automatic addition of shared or non-shared parameters to one or more family documents
 Process active family document or all families in a folder
 Uses FamilyManager class AddParameter methods
 Reads input data from parameter text files in Revit shared parameter format
DWGFamilyCreation
 Import DWG file into family document add type parameters to the imported instance
 DWGFileName with the DWG file name and ImportTime when it was imported
GenericModelCreation
 Create a generic model using extrusion, blend, revolution, sweep and swept blend elements
 Checks that open document is a family one or creates a new family document
 Exercises CreateSketchPlane, NewLineBound, and FamilyItemFactory methods to create profiles and shapes

Family API SDK Samples (cont.)
Learning resources
TypeRegeneration
 Use FamilyManager Types property to determine all types defined, and CurrentType to iterate through them
 Report whether all types regenerated successfully, log errors to file
ValidateParameters
 Check whether every type has valid values for certain parameters and log result to file
 External application subscribing to DocumentSaving and DocumentSavingAs events runs check automatically
 External command to launch manually
WindowWizard
 Create a window family via wizard user interface
 Start in window family template, e.g. Metric Window.rtf
 User defines input dimensions for window parameters and materials
 Create extrusion, alignment, dimension, reference plane, and family type

Family API SDK Samples (cont.)
Learning resources
CreateAirHandler – RME
 Create an air handler with pipe and duct connectors
 Check the template family category to verify valid starting point
 Use FamilyItemFactory class NewExtrusion, NewPipeConnector, NewDuctConnector methods
 Set proper connector parameters and use Document::CombineElements to join the extrusions
CreateTruss – RST
 Create a mono truss in a truss family document
 Create truss curves using NewModelCurve, set truss type through ModelCurve TrussCurveType property
 Add constraints to the truss curves with NewAlignment

and more …
Learning resources
Revit Developer Guide

 Family Creation
RevitAPI.chm
 Reference guide. Include code snippet
Recordings
 Revit Family API Webcast (July 2009)
 AU 2009 virtual class AU2009 CP9118-1 :
“The New Autodesk® Revit® Family API: Everything is Relative” by Jeremy Tammik
 In Revit 2010, but mostly still valid for Family API
 Based on the exercise labs
Discussion Groups >> Revit Architecture >> Revit API

API Training Classes
The Building Coder, Jeremy Tammik's Revit API Blog
ADN AEC Developer Blog
Autodesk Developer Network
DevHelp Online for ADN members
Summary
Revit Family from UI

 What is it?
 Where to begin, flavors, editor, what is possible
 Best practice
Family creation using API
 Learning along best practice
 Example: L-shape column
 Learning resources

Thank you very much!


3 Revit Family API

Uploaded by

Copyright:

3 Revit Family API

Uploaded by

Document Information

Original Title

Copyright

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

3 Revit Family API

Uploaded by

Copyright:

Revit Family API

Developer Technical Services

© 2013 Autodesk The Revit Family API

Goals of this talk

© 2013 Autodesk The Revit Family API

Revit Family from UI

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

Revit offers 6 basic family editors

Each family editor provides a specific set and is tied to the

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

 Formulas – can be used to control behaviour, visibility, arrays

 Advanced nesting – subcomponents can be swapped

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

Revit API within the family editor context

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

Incremental exercises to create a column family:

Lab1 – create a column family with rectangular profile

Include step-by-step instruction

© 2013 Autodesk The Revit Family API

Objective: learn THE basics of family API.

Classes and methods:

© 2013 Autodesk The Revit Family API

Objective: learn the basics of family API.

Classes and methods:

© 2013 Autodesk The Revit Family API

Objective: learn the basics of family API.

Classes and methods:

© 2013 Autodesk The Revit Family API

Classes and methods:

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

Right template (e.g., “Metric Column.rft”)

Upper Ref Level

Lower Ref. Level

© 2013 Autodesk The Revit Family API

Function ValidateDocument(ByVal rvtDoc As Document) As Boolean

© 2013 Autodesk The Revit Family API

Dim refPlane As ReferencePlane = _

© 2013 Autodesk The Revit Family API

Dim refPlane As ReferencePlane = _ z

Dim refPlane As ReferencePlane = _ z

© 2013 Autodesk The Revit Family API

Dim m_familyMgr As FamilyManager = m_rvtDoc.FamilyManager

© 2013 Autodesk The Revit Family API

'' add a parameter "Tw"

'' we will come back to setting to a solid later

© 2013 Autodesk The Revit Family API

For testing purposes

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

© 2013 Autodesk The Revit Family API

Function CreateSolid() As Extrusion

'' (2) create a sketch plane