•  

NewFamilyInstance Method (Face, XYZ, XYZ, FamilySymbol)

Inserts a new instance of a family onto a face of an existing element, using a location, reference direction, and a type/symbol.

Namespace: Autodesk.Revit.Creation
Assembly: RevitAPI (in RevitAPI.dll) Version: 17.0.0.0 (17.0.484.0)

Syntax

C# 
public FamilyInstance NewFamilyInstance(
	Face face,
	XYZ location,
	XYZ referenceDirection,
	FamilySymbol symbol
)
Visual Basic 
Public Function NewFamilyInstance ( _
	face As Face, _
	location As XYZ, _
	referenceDirection As XYZ, _
	symbol As FamilySymbol _
) As FamilyInstance
Visual C++ 
public:
FamilyInstance^ NewFamilyInstance(
	Face^ face, 
	XYZ^ location, 
	XYZ^ referenceDirection, 
	FamilySymbol^ symbol
)

Parameters

face
Type: Autodesk.Revit.DB Face
A face of a geometry object.
location
Type: Autodesk.Revit.DB XYZ
Point on the face where the instance is to be placed.
referenceDirection
Type: Autodesk.Revit.DB XYZ
A vector that defines the direction of the family instance. Note that this direction defines the rotation of the instance on the face, and thus cannot be parallel to the face normal.
symbol
Type: Autodesk.Revit.DB FamilySymbol
A FamilySymbol object that represents the type of the instance that is to be inserted. Note that this symbol must represent a family whose FamilyPlacementType is WorkPlaneBased.

Return Value

An instance of the new object if creation was successful, otherwise a null reference ( Nothing in Visual Basic) .

Remarks

Use this method to insert one family instance on a face of another element, using a point on the face and a vector to define the position and direction of the new symbol.

The type/symbol that is used must be loaded into the document before this method is called. Families and their symbols can be loaded using the Document.LoadFamily or Document.LoadFamilySymbol methods.

The host object must support insertion of instances, otherwise this method will fail. If the instances fails to be created an exception may be thrown.

Some Families, such as Beams, have more than one endpoint and are inserted in the same manner as single point instances. Once inserted, these linear family instances can have their endpoints changed by using the instance's Element.Location property.

Note: if the created family instance includes nested instances, the API framework will automatically regenerate the document during this method call.

Examples

Copy C# 
void CreateLightFixtureOnWall(Autodesk.Revit.DB.Document document, Wall wall)
{
    FilteredElementCollector collector = new FilteredElementCollector(document);
    collector.OfClass(typeof(FamilySymbol)).OfCategory(BuiltInCategory.OST_LightingFixtures);
    FamilySymbol symbol = collector.FirstElement() as FamilySymbol;

    // The only way to get a Face to use with this NewFamilyInstance overload
    // is from Element.Geometry with ComputeReferences turned on
    Face face = null;
    Options geomOptions = new Options();
    geomOptions.ComputeReferences = true;
    GeometryElement wallGeom = wall.get_Geometry(geomOptions);
    foreach (GeometryObject geomObj in wallGeom)
    {
        Solid geomSolid = geomObj as Solid;
        if (null != geomSolid)
        {
            foreach (Face geomFace in geomSolid.Faces)
            {
                face = geomFace;
                break;
            }
            break;
        }
    }

    // Get the center of the wall 
    BoundingBoxUV bboxUV = face.GetBoundingBox();
    UV center = (bboxUV.Max + bboxUV.Min) / 2.0;
    XYZ location = face.Evaluate(center);
    XYZ normal = face.ComputeNormal(center);
    XYZ refDir = normal.CrossProduct(XYZ.BasisZ);

    FamilyInstance instance = document.Create.NewFamilyInstance(face, location, refDir, symbol);         
}
Copy VB.NET 
Private Sub CreateLightFixtureOnWall(document As Autodesk.Revit.DB.Document, wall As Wall)
   Dim collector As New FilteredElementCollector(document)
   collector.OfClass(GetType(FamilySymbol)).OfCategory(BuiltInCategory.OST_LightingFixtures)
   Dim symbol As FamilySymbol = TryCast(collector.FirstElement(), FamilySymbol)

   ' The only way to get a Face to use with this NewFamilyInstance overload
   ' is from Element.Geometry with ComputeReferences turned on
   Dim face As Face = Nothing
   Dim geomOptions As New Options()
   geomOptions.ComputeReferences = True
   Dim wallGeom As GeometryElement = wall.Geometry(geomOptions)
   For Each geomObj As GeometryObject In wallGeom
      Dim geomSolid As Solid = TryCast(geomObj, Solid)
      If geomSolid IsNot Nothing Then
         For Each geomFace As Face In geomSolid.Faces
            face = geomFace
            Exit For
         Next
         Exit For
      End If
   Next

   ' Get the center of the wall 
   Dim bboxUV As BoundingBoxUV = face.GetBoundingBox()
   Dim center As UV = (bboxUV.Max + bboxUV.Min) / 2.0
   Dim location As XYZ = face.Evaluate(center)
   Dim normal As XYZ = face.ComputeNormal(center)
   Dim refDir As XYZ = normal.CrossProduct(XYZ.BasisZ)

   Dim instance As FamilyInstance = document.Create.NewFamilyInstance(face, location, refDir, symbol)
End Sub

Exceptions

Exception Condition
Autodesk.Revit.Exceptions ArgumentNullException Thrown when a non-optional argument was null.
Autodesk.Revit.Exceptions ArgumentException Thrown when the function cannot get the Reference from the face, or, when the Family cannot be placed as line-based on an input face reference, because its FamilyPlacementType is not WorkPlaneBased
Autodesk.Revit.Exceptions ArgumentsInconsistentException Thrown when reference direction is parallel to face normal at insertion point.
Autodesk.Revit.Exceptions InvalidOperationException Thrown when Revit is unable to place the family instance.
Autodesk.Revit.Exceptions ArgumentException Thrown if The symbol is not active.

See Also