第七章 國內綠建築指標的 BIM 應用
第三節 開發軟體 API 程式之系統架構
一、 Autodesk Revit 平台之物件資料結構
建築物的 BIM 模型是一種以物件導向技術為基礎的建築模型資料庫，資料 庫內容包含:三度空間資訊、材料資訊、法規資訊、交換標準、元件分類資訊 等。一個建築物的 BIM 模型，可以視為許多小型建築構件模型的集合，這些小 型建築元件模型的資料建構方式，影響了整體建築模型的資料品質。用於 BIM 專案中的元件模型，內部資料結構必須以標準化方式建構，使元件資訊能在設 計、施工、營運等各階段被正確轉換。本研究擬針對國內綠建築標章的規範內 容，建立可用於法規評估之標準元件庫。
在 Revit 平台中，圖形元素(Element)分為:模型元素、草圖元素、視圖元 素、群組元素、標註元素、與專案資訊元素等六種。這些圖形元素都源自於族 群物件(Family)，一個族群物件可再向下細分為多種族群類型(Family
Symbol)。不論族群物件或族群類型，都只是抽象的物件分類或幾何組態，這些 族群類型都必須以族群例證(Family Instance)的方式置入模型中，才能使該種 族群成為一個模型中的實體元素。以族群為基礎的 Revit 圖形元素其分層關係 如表 7-2 所示。
表 7-2：以族群為基礎的 Revit 圖形元素，有以上幾個分層(本研究製表) 構件品類 (Category) 建築構造的主要分類
族群物件 (Family) 預先以族群設計樣板設定好的族群物件組態
族群類型 (Family Symbol) 一族群物件可依照不同屬性，再向下細分成多個類型
族群例證 (Family Instance) 例證為族群之實體物件，不同實體物件可以歸屬自同一種族群
84
模型元素(Model Element)指的建築專案模型中的實體構造物件。模型元素的族 群分為二大類:
系統族群 (System Family):
由 Revit 所預定的系統族群所產生的例證物件。模型的主要元素(Host Element)，可以被其他模型所依附，例如:Wall、Roof、Ceiling、Floor 等。
一般元件族群 (Component Family):
一般元件族群所產生的例證物件，可由使用者自行在 Revit 平台下的族群 編輯器中，預先為該種物件設定幾何組態及相關參數，再載入 Revit
Architecture 專案模型中。Revit 平台中，一般元件族群的檔案可隨建築專案 模型的.RVT 檔一併儲存，也可以另行保存為.RFA 格式的檔案。
族群物件是由一系列參數所定義，族群參數紀錄了該物件的各種資訊，如 幾何尺寸、材料屬性、插入位置、模型面向、辨識碼、分類屬性等，這些參數 資訊是為建築資訊模型技術的基礎。族群參數可在族群編輯器中進行設置，參 數與參數之間可以具有連動關係，依照前提操作條件自動更新相關參數。族群 參數可以與外部的資料庫進行連結，依照給定條件自動檢索相關數值，也能夠 藉由外部 API 程式進行資料擷取及資料整合。
85
二、 Revit 平台之 API 基本程式模塊 1. 篩選元素(Element Filtering)
Revit Api 中的 FilteredElementCollector 的類物件，可用篩選與迭代 (Filtering and Iteration)的演算方式，依序搜索模型的每一個元素，若元素 符合標準則加入選取集合中，可建立一套元素套篩選集合。
表 7-3：API 篩選元素程式碼片段(本研究製表)
功能與目的
以物件類型來篩選物件，選出模型中類型為"內建窗(OST_Windows)"的物件 外部應用指令-根據品類篩選物件
using Autodesk.Revit.ApplicationServices;
using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
using Autodesk.Revit.UI.Selection;
using System.Collections.Generic;
using System.Linq;
namespace RevitApi.Awsg {
[Transaction(TransactionMode.Manual)]
public class FilterElementByCategory : IExternalCommand {
public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements) {
FilteredElementCollector collector = new FilteredElementCollector(_doc);
// 設定此收集器，以例證層級進行物件篩選
collector = collector.OfClass(typeof(FamilyInstance));
collector = collector.OfCategory(BuiltInCategory.OST_Windows);
IList<Element> WindowsList = collector.ToList<Element>();
86
using Autodesk.Revit.ApplicationServices;
using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
using Autodesk.Revit.UI.Selection;
using System.Collections.Generic;
using System.Linq;
namespace RevitApi.Awsg {
[Transaction(TransactionMode.Manual)]
public class FilterElementByTypeName : IExternalCommand {
public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements) {
UIApplication uiApp = commandData.Application;
UIDocument uiDoc = uiApp.ActiveUIDocument;
FilteredElementCollector collector = new FilteredElementCollector(_doc);
// 設定此收集器，以例證層級進行物件篩選
collector = collector.OfClass(typeof(FamilyInstance));
// 以Linq語法查詢收集器中的元件，找出物件的子類型名稱符合"特定名稱"者
var query = from element in collector where element.Name == "AwsgWindow_01" select element;
IList<Element> WindowsList = query.ToList<Element>();
// 在模型中執行選取，把表列中的元件以亮顯方式呈現在模型中
foreach (Element elem in WindowsList) { selection.Elements.Add(elem); } return Result.Succeeded;
87
2. 參數檢索(Retrieval Parameter)
在 Revit API 中，有二種方式可以檢索一物件的參數:
•使用 Element.Parameters 方法 – 用以取得某物件的整套參數。
•使用 Element.Paramater 方法 – 用以取得某物件的單一參數，必須以特定 方式宣告。
使用 Element.Parameters 方法
以 Parameters()方法檢索某物件的整套參數，由於一物件的各項參數可能 具有不同的資料格式(StorageType)，這些資料格式可能為整數(Integer)、雙 精確度之浮點數(Double)、字串(String) 或 元素識別碼(ElementId)。因此擷 取整套物件參數時，必須先對原始的參數資料進行資料格式的分析。
using Autodesk.Revit.ApplicationServices;
using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
using Autodesk.Revit.UI.Selection;
using System.Text;
namespace RevitApi.Awsg {
[Transaction(TransactionMode.Manual)]
public class RetrieveProperty : IExternalCommand {
public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements) {
ElementType elemType = (ElementType)_doc.GetElement(elemTypeId);
string height = "null";
88
var x1 = singleElement.get_Parameter("X1").AsDouble().ToString();
var x2 = singleElement.get_Parameter("X2").AsDouble().ToString();
var y1 = singleElement.get_Parameter("Y1").AsDouble().ToString();
var y2 = singleElement.get_Parameter("Y2").AsDouble().ToString();
var Ai = singleElement.get_Parameter("Ai").AsDouble().ToString();
var Ki = singleElement.get_Parameter("ηi").AsDouble().ToString();
var ηi = singleElement.get_Parameter("ηi").AsDouble().ToString();
var depthRatio = singleElement.get_Parameter("DepthRatio").AsDouble().ToString();
var AWSGi = singleElement.get_Parameter("AWSGi").AsDouble().ToString();
pStr.Append(
LocationPoint elemLocation = singleElement.Location as LocationPoint; //取得位置及旋轉角 var LocationX = elemLocation.Point.X.ToString();
System.Windows.Forms.MessageBox.Show(pStr.ToString(), "Retrieve Property");
return Result.Succeeded;
89
使用 Element.Paramater 方法
以 Parameter()方法來取得物件的特定一項參數，有以下四種方式來指定參 數：
• Parameter(BuiltInParameter) –以內建參數的識別碼
• Parameter(String) – 以參數的名稱字串
• Parameter(Definition) – 以參數的定義
• Parameter(GUID) – 以共享參數的全局識別碼來取得共享參數
Revit 平台下所涵蓋的參數範圍高達數百項，但一個模型物件僅用到數十 種，而其中與單次 API 功能相關的參數也僅有少數幾項，因此如何在眾多參數 中辨別最重要的關鍵參數，是開發過程的重要工作。在 Revit API 的軟體開發 套件(SDK)中，提供一個 RevitLookup 的外掛程式可以協助開發者，來檢視建 築元件的參數名稱，找出與目前開發功能相關的參數。
圖 7-2：藉由 RevitLookup 工具所顯示的物件內建參數(BuiltInParameter)
(圖片來源 The Revit API training material from the Revit Developer Center.
http://usa.autodesk.com/adsk/servlet/index?id=2484975&siteID=123112)
90
以下程式碼，以 Element.get_Parameter()的方法，可以直接以參數名稱字串 或內建參數的識別名稱，來指定某一項所欲檢索的參數。
//宣告一個Parameter物件 Parameter param ;
//檢索參數: SYMBOL_FAMILY_AND_TYPE_NAMES_PARAM (物件類型) //若欄位非空白，則以將參數資料轉換為字串格式
param = elem.get_Parameter(
BuiltInParameter.SYMBOL_FAMILY_AND_TYPE_NAMES_PARAM);
if (param != null)
//This code snippets reference and modified from
//The Revit API training material from the Revit Developer Center.
//http://usa.autodesk.com/adsk/servlet/index?id=2484975&siteID=123112
91
using Autodesk.Revit.ApplicationServices;
using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
using Autodesk.Revit.UI.Events;
using Autodesk.Revit.UI.Selection;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Reflection;
using System.Windows.Media.Imaging;
namespace RevitApi.Awsg {
[Transaction(TransactionMode.Manual)]
public class ExtendingFields : IExternalCommand {
// 取得目前dll檔的完整路徑+檔名
string AssemblyFullName { get { return Assembly.GetExecutingAssembly().Location; } } // 取得目前dll檔所在資料夾路徑
string AssemblyPath { get { return Path.GetDirectoryName(AssemblyFullName); } }
public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements) {
System.IO.FileStream extendingParamFileStream = System.IO.File.Create(AssemblyPath + "\\extendingParamFile.txt");
extendingParamFileStream.Close();
// 設定共用參數文字檔的檔案路徑，並開啟共用參數文字檔
_doc.Application.SharedParametersFilename = AssemblyPath + @"\extendingParamFile.txt";
DefinitionFile sharedParameterFile = _doc.Application.OpenSharedParameterFile();
Transaction ts = new Transaction(_doc);
private void addingCustomField(string newField, DefinitionFile sharedParameterFile, UIApplication app)
{
// 在共享文件中新增一個參數群組("群組名稱")
DefinitionGroup newGroup = sharedParameterFile.Groups.Create("AWSG Group");
// 在共享文件中新增一個參數("參數名稱",指定參數類型)
Definition newDefinition = newGroup.Definitions.Create(newField, ParameterType.Length);
// 創建一個新的品類群組，並把加入窗品類
92
app.ActiveUIDocument.Document.Settings.Categories.get_Item(BuiltInCategory.OST_Windows);
newCategorieSet.Insert(newCategory);
// 使用例證綁定方式，把參數加入到每個窗品類物件的例證欄位 InstanceBinding instanceBinding =
app.Application.Create.NewInstanceBinding(newCategorieSet);
// 將客製化的參數定義加入到文件中
BindingMap bindingMap = app.ActiveUIDocument.Document.ParameterBindings;
bool instanceBindngIsDone = bindingMap.Insert(newDefinition, instanceBinding, BuiltInParameterGroup.PG_GREEN_BUILDING);
93
三、 RevitAPI 整合介面
本研究以 Revit API Exterinal Application 製作一個整合物件篩選、參數檢 測、參數更新的 Revit 外掛程式介面。
圖 7-3：Revit API 整合介，面一個整合篩選器與參數檢索的物件管理介面(本研究製作)
圖 7-4：介面操作步驟，①點選篩選條件②左側欄顯示符合篩選條件之物件③勾選欲檢索之物 件④點選按鈕，把勾選物件顯示於右側⑤右側欄位列示被勾選物件之各項屬性(本研究製作)
94 圖 7-5：物件選取功能(本研究製作)
圖 7-6：API 射線法操作步驟(本研究製作)
圖 7-7：物件屬性變更(本研究製作)
95