Revit API 官方文档翻译与解读：Construction Modeling 构造建模

Construction Modeling 构造建模

官方链接
The Revit API allows elements to be devided into sub-parts or collected into assemblies to support construction modeling workflows, much the same way as can be done with the Revit user interface.
Revit API 允许把元素分割为多个零件或者组合为装配，用来支持构造建模工作流。分割和装配的行为和用户通过UI界面进行操作是一致的。
Both parts and assemblies can be independently scheduled, tagged, filtered, and exported.
零件和装配都可以独立排程、标记、过滤和导出。
You can also divide a part into smaller parts.
你也可以把一个零件进一步细分为多个更小的零件。
After creating an assembly type, you can place additional instances in the project and generate isolated assembly view.
在创建好一个装配类型之后，你可以在项目中放置多个实例和生成独立的装配视图。

The main classes related to Construction Modeling are:
以下是构造建模相关的主要类：
AssemblyInstance - This class combines multiple elements for tagging, filtering, scheduling and creating isolated assembly views.
AssemblyInstance - 这个类将多个元素组合，可进行标记、过滤、排程和创建独立的装配视图。
AssemblyType - Represents a type for construction assembly elements. Each new unique assembly created in the project automatically creates a corresponding AssemblyType. A new AssemblyInstance can be placed in the document from an existing AssemblyType.
AssemblyType - 表示施工装配元素的类型。一个新的唯一的装配在项目中被创建，会自动创建一个对应的装配类型AssemblyType。可以用已有的装配类型AssemblyType在文档中创建新的装配实例AssemblyInstance。
PartUtils - This utility class contains general part utility methods,including the ability to create parts, divide parts, and to get information about parts.
PartUtils - 这个实用工具类包含了一些常规的零件实用方法，包括创建零件、分割零件和从零件中获取信息。
AssemblyViewUtils - A utility class to create various type of assembly views.
AssemblyViewUtils - 一个创建各种类型装配视图的实用工具类。

Assemblies and Views 装配和视图

You can combine any number of model elements to create an assembly, which can then be edited, tagged, scheduled, and filtered.
你可以通过合并任意数量的元素来创建一个装配组件，这个装配组件可以被编辑、打标签、被收录到明细表，以及过滤（一般是通过过滤，把不同类型分别出来）。
Creating assemblies
创建装配
The static Create() method of the AssemblyInstance class is used to create a new assembly instance in the project. The Create() method must be created inside a transaction and the transaction must be committed before performing any action on the newly created assembly instance. The assembly type is assigned after the transaction is complete. Each unique assembly has its own AssemblyType.
AssemblyInstance这个类的静态方法Create()被用来在项目中创建装配的实例。静态方法Create()必须在一个事务中进行，并且只有在事务被提交之后，才能对新创建的装配实例进行操作。装配的类型是在事务结束之后才被赋值的。每一个独立的装配，都有自己的对应类型，在代码里是AssemblyType。
The following example creates a new assembly instance, changes the name of its AssemblyType and then creates some views for the assembly instance.
下面这个例子是创建一个新的装配实例，修改它对应的类型AssemblyType的名称，然后为这个装配实例创建一些视图。

AssemblyInstance CreateAssemblyAndViews(Autodesk.Revit.DB.Document doc, ICollection<ElementId> elementIds) {
	AssemblyInstance assemblyInstance = null;
	using(Transaction transaction = new Transaction(doc)){
		if(AssemblyInstance.IsValidNamingCategory(doc, categoryId, elementIds)){
			transaction.Start("Create Assembly Instance");
			assemblyInstance = AssemblyInstance.Create(doc, elementIds, categoryId);
			transaction.Commit();
			
			if(transaction.GetStatus() == TransactionStatus.Committed) {
				transaction.Start("Set Assembly Name");
				assemblyInstance.AssemblyTypeName = "My Assembly Name";
				transaction.Commit();
			}
			
			if(assemblyInstance.AllowAssemblyViewCreation()){
				if(transaction.GetStatus() == TransactionStatus.Commited) {
					transaction.Start("View Creation");
					View3D view3d = AssemblyViewUtils.Create3DOrthographic(doc, assemblyInstance.Id);
					ViewSchedule partList = AssemblyViewUtils.CreatePartList(doc, assemblyInstance.Id);
					transaction.Commit();
				}
			}
		}
	}
	
	return assemblyInstance;
}

Another way to create an AssemblyInstance is to use an existing AssemblyType. To create an AssemblyInstance using an AssemblyType, use the static method AssemblyInstance.PlaceInstance() and specify the ElementId of the AssemblyType to use and a location at which to place the assembly.
另一种创建装配实例AssemblyInstance的方式是通过已经存在的装配类型AssemblyType去创建。为了通过已有装配类型AssemblyType去创建一个装配实例AssemblyInstance，可以调用静态方法 AssemblyInstance.PlaceInstance()，需传递对应的装配类型AssemblyInstance的ElementId，以及这个装配需要放置的坐标位置。

Assembly Views
Various assembly views can be created for an assembly instance using static methods of the AssemblyViewUtils class, including an orthographic 3D assembly view, a detail section assembly view, a material takeoff multicategory schedule assembly view, a part list multicategory schedule assembly view, a single-category schedule and a sheet assembly view.
通过AssemblyViewUtils类的静态方法，可以为一个装配实例创建多种装配视图，包括一个正交的三维装配视图、一个装配剖面详图、一个多类别材质明细表视图、一个多类别零件明细表装配视图、一个单类比明细表和一个图纸装配视图。
All of these except sheet views have overloaded creation methods which create the schedule or view from a template. In addition to a template Id, these overloads have a parameter to indicate if the template will be assigned or applied.
除了图纸视图，这些创建方法都是重载的，都是从一个模板来创建明细表或者视图。除了模板的Id，这些重载还有一个参数标识模板是被分配或应用。
Note that assembly views must all be assigned to the same assembly instance of the assembly type. AssemblyInstance.AllowsAssemblyViewCreation() returns true if that assembly instance can accept new assembly views (either because it already has views or because no assembly instance has views.)
注意装配视图必须被分配一个同一个装配类型的装配实例。如果装配实例可以接受新的装配视图，那么AssemblyInstance.AllowsAssemblyViewCreation()返回true。（无论是因为它已经有视图了或者没有装配实例有视图。）
The following example creates a new single-category schedule for an assembly from a given template.
下面这个例子从一个模板为一个装配创建了一个新的单类别明细表。
Code Region: Create assembly view from template
代码片段：从模板创建装配视图

private ViewSchedule CreateScheduleForAssembly(Document doc, AssemblyInstance assemblyInstance, ElementId viewTemplateId) {
	ViewSchedule schedule = null;
	if(assemblyInstance.AllowAssemblyViewCreation()){
		using(Transaction transaction = new Transaction(doc)) {
			transaction.Start("Create Schedule");
			if(ViewSchedule.IsValidCategoryForSchedule(assemblyInstance.NamingCategoryId)) {
				schedule = AssemblyViewUtils.CreateSingleCategorySchedule(doc, assemblyInstance.Id, assemblyInstance.NamingCategoryId, viewTemplateId, false);
			}
			transaction.Commit();
			
			if(schedule != null && transaction.GetStatus() == Transaction.Committed) {
				transaction.Start("Edit Schedule");
				schedule.Name = "AssemblyViewSchedule";
				transaction.Commit();
			}
		}
	}
	return schedule;
}

The document must be regenerated before using any of these newly created assembly views.
在使用新创建的装配视图之前，需要对文档进行重新生成（可以理解为刷新）。
You’ll note in the example above that a transaction is committed after creating a new assembly view.
在上面的例子里，你会注意到，在创建一个新的装配视图之后，需要提交事务。
The Commit() method automatically regenerates the document.
Commit() 这个方法自动刷新了文档。

Parts 零件

Parts can be generated from elements with layered structures, such as:
Walls (excluding stacked walls and curtain walls)
Floors (excluding shape-edited floors)
Roofs (excluding those with ridge lines)
Ceilings
Structural slab foundations
零件可以从有复合结构的元素中生成出来，例如：
墙（不包括叠层墙和幕墙）
楼板（不包含形状被编辑过的楼板）
屋顶（不包含有脊线的屋顶）
天花板
结构基础底板

In the Revit API, elements can be divided into parts using the PartUtils class.
在 Reivit API 中，可以通过使用PartUtils类将元素分割为零件。
The static method PartUtils.CreateParts() is used to create parts from one or more elements.
静态方法PartUtils.CreateParts() 被用来从一个或多个元素创建零件。
Note that this method instantiates a PartMaker and creates Parts that will be split into smaller parts if you chose to use DivideParts.
需要注意，这个方法初始化了一个PartMaker并且创建了零件。后续，你可以通过使用DivideParts来把这些零件分割为更小的零件。
The PartMaker uses its embeded rules to drive creation of the needed parts during regeneration.
PartMaker使用内置的规则在文档重新生成时控制所需零件的创建过程。

The API also offers an interface to subdivide parts.
API还提供了一个细分零件的接口。
PartUtils.DivideParts() accepts as input a collection of part ids, a collection of “intersecting element” ids (which can be layers or grids), and a collection of curves.
PartUtils.DivideParts() 这个方法的输入参数接受一个零件id的集合、一个相交元素id的集合和一个曲线的集合。
The routine uses the intersecting elements and curves as boundaries from which to divide and generate new parts.
通常，相交元素和曲线会被用作边界来分割和生成新的零件。

The GetAssociatedParts() method can be called to find some or all of the parts associated with an element, or use HasAssociatedParts() to determine if an element has parts.
GetAssociatedParts()方法可以被调用来找到和一个元素相关的一些或全部的零件，或者，可以调用HasAssociatedParts()来确定一个元素是否有零件。

You can delete parts through the API either by deleting the individual part elements, or by deleting the PartMaker associated to the parts (which will delete all parts generated by this PartMaker after the next regeneration).
有两种方法可以删除零件，通过API来删除单个零件元素，或者通过删除和零件相关的PartMaker（当PartMaker被删除后，在下一次文档重新生成时，会删除所有的零件。）

Parts can be manipulated in the Revit API much the same as they can in the Revit user interface. For example, the outer boundaries of parts may be offset with PartUtils.SetFaceOffset().
零件在API中的操作方式和通过UI接口操作基本保持一致。例如，可以通过PartUtils.SetFaceOffset()来偏移零件的外边界。

The following example offsets all the faces of a part that can be offset.
下面这个把一个零件所有可以偏移的面都做了偏移。
Code Region: Offset Faces of a Part
代码片段：偏移一个零件的面

public void OffsetPartFaces(Part part) {
	Document doc = part.Document;
	Autodesk.Revit.DB.GeometryElement geomElem = part.get_Geometry(new Options());
	
	foreach(GeometryObject geomObject in geomElem) {
		if(geomObject is Solid){
			Solid solid = geomObject as Solid;
			FaceArray faceArray = solid.Faces;
			foreach(Face face in faceArray) {
				if(part.CanOffsetFace(face)){
					part.SetFaceOffset(face,1);
				}
			}
		}
	}
}

Before and After Offseting faces of a selected Part
一个零件面偏移前后对比

Returning the entities that create a divided Part
返回创建分割零件后的实体

These methods identify and return the curves that were sketched to create the part division and, optionally, also outputs the sketch plane for those curves.
这些方法可以识别和返回那些被用于分割零件的曲线，另外，一个可选的参数，也可以返回这些曲线对应的草图平面。

PartUtils.GetSplittingCurves(Document, ElementId)
PartUtils.GetSplittingCurves(Document, ElementId, out SketchPlane)

PartUtils.GetSplittingElements(Document, ElementId) identifies and return the elements (ReferencePlane, Level or Grid) that were used to create the division.
PartUtils.GetSplittingElements(Document, ElementId) 识别和返回用来创建分割的元素（参考平面、标高、轴网）。

Parts and Direct Shapes
零件和直接图形
Parts can be created from DirectShape instances, either in the same host document or in a link. These methods indicate whether it is possible to create parts from an instance of one of those classes.
零件可以从直接图形DirectShape的实例中创建出来，无论该实例时在主文档还是链接文档里。这些方法表示是否可以从这些类的实例上创建零件。
DirectShape.CanCreateParts()
DirectShapeType.CanCreateParts()

版本修订：
Version 1 - 2024/6/26
Version 2 - 2024/7/1