Revit API: 创建族实例 FamilyInstance

前言

族（Family）作为 Revit 的一个核心，API 提供了很好的支持。本文是我自己对族相关的认识，供自己以后查询和参考。

创建族实例

代码来源 Revit 官方文档。
如果你找到某个 element 的创建方法，那么它多半在 Autodesk.Revit.Creation.Document。
下面是创建族实例相关接口，参数的不同表明他们适用于不同的族类型。如果你使用了错误的接口，族实例可能会创建成功，但是它的行为可能不正常。 所以，一定要自己弄明白自己创建的族的类型。

namespace Autodesk.Revit.Creation
{
     
    public class Document : ItemFactoryBase
    {
     
        // 创建族实例相关接口
        public FamilyInstance NewFamilyInstance(DB.XYZ location, DB.FamilySymbol symbol, DB.Element host, Level level, StructuralType structuralType);
        public FamilyInstance NewFamilyInstance(DB.XYZ location, DB.FamilySymbol symbol, Level level, StructuralType structuralType);
        public FamilyInstance NewFamilyInstance(Curve curve, DB.FamilySymbol symbol, Level level, StructuralType structuralType);
    }
}

而 ItemFactoryBase 里还有另外9个创建族实例的接口：

namespace Autodesk.Revit.Creation
{
     
    public class ItemFactoryBase : APIObject
    {
     
        // 创建族实例相关接口
        public FamilyInstance NewFamilyInstance(DB.XYZ location, DB.FamilySymbol symbol, DB.XYZ referenceDirection, DB.Element host, StructuralType structuralType);
        public FamilyInstance NewFamilyInstance(Face face, DB.XYZ location, DB.XYZ referenceDirection, DB.FamilySymbol symbol);
        public FamilyInstance NewFamilyInstance(Face face, Line position, DB.FamilySymbol symbol);
        public FamilyInstance NewFamilyInstance(DB.XYZ location, DB.FamilySymbol symbol, DB.Element host, StructuralType structuralType);
        public FamilyInstance NewFamilyInstance(Reference reference, Line position, DB.FamilySymbol symbol);
        public FamilyInstance NewFamilyInstance(DB.XYZ origin, DB.FamilySymbol symbol, View specView);
        public FamilyInstance NewFamilyInstance(Line line, DB.FamilySymbol symbol, View specView);
        public FamilyInstance NewFamilyInstance(Reference reference, DB.XYZ location, DB.XYZ referenceDirection, DB.FamilySymbol symbol);
        public FamilyInstance NewFamilyInstance(DB.XYZ location, DB.FamilySymbol symbol, StructuralType structuralType);
    }
}

五个例子

下面摘录了文档里的四个例子，还有其他例子，可自行翻阅：

1. Host Based 族 - 在墙上创建门
2. 仅仅需要一个点作为位置的族 - 创建柱子
3. 需要一条位置线的族 - 创建梁
4. Host Based 并且需要位置线的族 - 在墙上创建加固件
5. 需要一条位置线（比第 3 个例子少一个参数） - 创建细节构件

在墙上创建门

用带 host 参数的这个接口：

public FamilyInstance NewFamilyInstance(DB.XYZ location, DB.FamilySymbol symbol, DB.Element host, Level level, StructuralType structuralType);

步骤：

1. 找到所有门的 FamilySymbol
2. 在墙上不同位置创建族实例 FamilyInstance

void CreateDoorsInWall(Autodesk.Revit.DB.Document document, Wall wall)
{
     
    // get wall's level for door creation
    Level level = document.GetElement(wall.LevelId) as Level;

    FilteredElementCollector collector = new FilteredElementCollector(document);
    ICollection<Element> collection = collector.OfClass(typeof(FamilySymbol))
                                               .OfCategory(BuiltInCategory.OST_Doors)
                                               .ToElements();
    IEnumerator<Element> symbolItor = collection.GetEnumerator();

    double x = 0, y = 0, z = 0;
    while (symbolItor.MoveNext())
    {
     
        FamilySymbol symbol = symbolItor.Current as FamilySymbol;
        XYZ location = new XYZ(x, y, z);
        FamilyInstance instance = document.Create.NewFamilyInstance(location, symbol, wall, level, StructuralType.NonStructural);
        x += 10;
        y += 10;
        z += 1.5;
    }
}

创建柱子

仅仅需要柱子的位置，类型和楼层。

public FamilyInstance NewFamilyInstance(DB.XYZ location, DB.FamilySymbol symbol, Level level, StructuralType structuralType);

步骤：

1. 找到柱子的 FamilySymbol
2. 在原点创建族实例 FamilyInstance

FamilyInstance CreateColumn(Autodesk.Revit.DB.Document document, Level level)
{
     
    // Get a Column type from Revit
    FilteredElementCollector collector = new FilteredElementCollector(document);
    collector.OfClass(typeof(FamilySymbol)).OfCategory(BuiltInCategory.OST_StructuralColumns);
    FamilySymbol columnType = collector.FirstElement() as FamilySymbol;

    FamilyInstance instance = null;
    if (null != columnType)
    {
     
        // Create a column at the origin
        XYZ origin = new XYZ(0, 0, 0);

        instance = document.Create.NewFamilyInstance(origin, columnType, level, StructuralType.Column);
    }

    return instance;
}

创建梁

需要使用带位置线的接口：

public FamilyInstance NewFamilyInstance(Curve curve, DB.FamilySymbol symbol, Level level, StructuralType structuralType);

步骤：

1. 找到梁的 FamilySymbol
2. 给定位置线创建族实例 FamilyInstance

FamilyInstance CreateBeam(Autodesk.Revit.DB.Document document, View view)
{
     

   // get the given view's level for beam creation
    Level level = document.GetElement(view.LevelId) as Level;

    // get a family symbol
    FilteredElementCollector collector = new FilteredElementCollector(document);
    collector.OfClass(typeof(FamilySymbol)).OfCategory(BuiltInCategory.OST_StructuralFraming);

    FamilySymbol gotSymbol = collector.FirstElement() as FamilySymbol;

    // create new beam 10' long starting at origin
    XYZ startPoint = new XYZ(0, 0, 0);
    XYZ endPoint = new Autodesk.Revit.DB.XYZ(10, 0, 0);

    Autodesk.Revit.DB.Curve beamLine = Line.CreateBound(startPoint, endPoint);

    // create a new beam
    FamilyInstance instance = document.Create.NewFamilyInstance(beamLine, gotSymbol,
                                                                level, StructuralType.Beam);

    return instance;
}

在墙上创建加固件

放置基于面的族实例的接口：

public FamilyInstance NewFamilyInstance(Face face, Line position, DB.FamilySymbol symbol);

步骤：

1. 找到加固件的 FamilySymbol
2. 遍历墙的几何图形来找一个 Face
3. 用这个 Face 和在它上面创建的 Line 创建族实例 FamilyInstance

public void PlaceStiffenerOnWallFace(Autodesk.Revit.DB.Document doc, Wall wall)
{
     
    // The structural stiffeners family type is compatible with line-based face placement
    FilteredElementCollector fsCollector = new FilteredElementCollector(doc);
    fsCollector.OfClass(typeof(FamilySymbol)).OfCategory(BuiltInCategory.OST_StructuralStiffener);
    FamilySymbol stiffenerSymbol = fsCollector.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;
        }
    }

    // Generate line for path
    BoundingBoxUV bbox = face.GetBoundingBox();
    UV lowerLeft = bbox.Min;
    UV upperRight = bbox.Max;
    double deltaU = upperRight.U - lowerLeft.U;
    double deltaV = upperRight.V - lowerLeft.V;
    double vOffset = deltaV * 0.80; // 80% up the wall face

    UV firstPoint = lowerLeft + new UV(deltaU * 0.30, vOffset);
    UV lastPoint = lowerLeft + new UV(deltaU * 0.70, vOffset);

    Line line = Line.CreateBound(face.Evaluate(firstPoint), face.Evaluate(lastPoint));

    doc.Create.NewFamilyInstance(face, line, stiffenerSymbol);     
}

需要一条位置线（比第 3 个例子少一个参数） - 创建细节构件

放置细节族实例的接口：

public FamilyInstance NewFamilyInstance(Line line, DB.FamilySymbol symbol, View specView);

步骤：

1. 找到细节构件的 FamilySymbol，BuiltInCategory.OST_DetailComponents
2. 创建一条线 Line
3. 用这个 Line 创建族实例 FamilyInstance

void CreateDetailComponent(Autodesk.Revit.DB.Document document, View view)
{
     
    // Create a detail component in the given view if it is a detail or drafting view
    if (view.ViewType == ViewType.Detail ||
        view.ViewType == ViewType.DraftingView)
    {
     
        FamilySymbol symbol = null;
        FilteredElementCollector fsCollector = new FilteredElementCollector(document);
        fsCollector.OfClass(typeof(FamilySymbol)).OfCategory(BuiltInCategory.OST_DetailComponents);
        ICollection<Element> collection = fsCollector.ToElements();
        foreach (Element element in collection)
        {
     
            FamilySymbol current = element as FamilySymbol;
            // This NewFamilyInstance overload requires a curve based family
            if (current.Family.FamilyPlacementType == FamilyPlacementType.CurveBasedDetail)
            {
     
                symbol = current;
                break;
            }
        }

        if (symbol != null)
        {
     
            // create a 2' detail component at the view's origin
            XYZ start = view.Origin;
            XYZ end = start + new XYZ(2, 0, 0);

            Line line = Line.CreateBound(start, end);

            FamilyInstance instance = document.Create.NewFamilyInstance(line, symbol, view);
        }
    }
}