C#開發BIMFACE系列27 服務端API之獲取模型數據12：獲取構件分類樹
- 2019 年 10 月 3 日
- 筆記
BIMFACE官方示例中，載入三維模型後，模型瀏覽器中左上角默認提供了“目錄樹”的功能，清晰地展示了模型的完整構成及上下級關係。
本篇介紹如何獲取單個模型的構件分類樹資訊。
請求地址：POST https://api.bimface.com/data/v2/files/{fileId}/tree
說明：單模型構件分類樹, treeType 接受兩個值：default 和 customized，默認為 default。
v參數用來區別 treeType 為 default 時返回樹的格式， customized總是返回格式2.0的構件樹。
參數：
v參數用來區別 treeType 為 default 時返回樹的格式， customized總是返回格式2.0的構件樹。
當 treeType 為”customized”時，desiredHierarchy 表示了篩選樹的層次,可選值有building,systemType,specialty,floor,category,family,familyType，如:desiredHierarchy=specialty,systemtype。
customizedNodeKeys：用來指定篩選樹每個維度用id或者是name作為唯一標識, 如”floor”:”id”。
請求 path(示例)：https://api.bimface.com/data/v2/files/1211223382064960/tree?v=2.0
請求 header(示例)：“Authorization: Bearer dc671840-bacc-4dc5-a134-97c1918d664b”
請求 body(示例)：可以為空，不傳遞。
HTTP響應示例(200)：
{ "code": "success", "message": null, "data": [ { "actualName": "1F", "data": null, "elementCount": 18, "id": "694", "items": [ { "actualName": "欄杆扶手", "data": null, "elementCount": 18, "id": "-2000126", "items": [ { "actualName": "欄杆扶手", "data": null, "elementCount": 18, "id": "", "items": [ { "actualName": "欄杆", "data": null, "elementCount": 1, "id": null, "items": [], "name": "欄杆", "type": "familyType" } ], "name": "欄杆扶手", "type": "family" } ], "name": "欄杆扶手", "type": "category" } ], "name": "1F", "type": "floor" } ] }
返回的結果結構比較複雜，封裝成對應的C#類如下：
/// <summary> /// 獲取單個模型的構件分類樹(2.0的默認分類樹 floor, category, family, familyType)返回的結果類（默認模式） /// </summary> [Serializable] public class SingleModelTree : GeneralResponse<List<TreeItem>> { }
調用的 TreeItem 類
[Serializable] public class TreeItem { /// <summary> /// 項的名稱 /// </summary> [JsonProperty("actualName")] public string ActualName { get; set; } [JsonProperty("data")] public string Data { get; set; } [JsonProperty("elementCount")] public int? ElementCount { get; set; } [JsonProperty("id")] public string Id { get; set; } [JsonProperty("items")] public TreeItem[] Items { get; set; } [JsonProperty("name")] public string Name { get; set; } /// <summary> /// 例如：familyType、family、category /// </summary> [JsonProperty("type")] public string Type { get; set; } /// <summary>返回表示當前對象的字元串。</summary> /// <returns>表示當前對象的字元串。</returns> public override string ToString() { return String.Format("[actualName={0}, data={1}, elementCount={2}, id={3}, items={4}, name={5}, type={6}]", ActualName, Data, ElementCount, Id, Items.ToStringLine(), Name, Type); } }
請注意 TreeItem 類中的 public TreeItem[] Items { get; set; } 屬性，類型是該類本身。屬於遞歸引用。
Newtonsoft.Json.dll 默認支援遞歸引用類的序列化與反序列化。
C#實現方法：
1 /// <summary> 2 /// 獲取單個模型中構件的默認分類樹 3 /// </summary> 4 /// <param name="accessToken">【必填】令牌</param> 5 /// <param name="fileId">【必填】代表該單模型的文件ID</param> 6 /// <param name="v">【非必填】用來區別treeType為default時返回樹的格式</param> 7 /// <param name="request">【非必填】其他過濾參數類對象</param> 8 /// <returns></returns> 9 public virtual SingleModelTree GetSingleModelTreeByDefault(string accessToken, long fileId, string v = "2.0", FileTreeRequestBody request = null) 10 { 11 //return GetSingleModelTree(accessToken, fileId, TreeType.Default, v, request); 12 /* 單模型構件分類樹, 13 （1）treeType 接受兩個值：default 和 customized，默認為 default。 14 （2）v 參數用來區別 treeType 為 default 時返回樹的格式, customized 總是返回格式2.0的構件樹。 15 （3）當 treeType 為"customized"時，FileTreeRequestBody 類的 desiredHierarchy 屬性 表示了篩選樹的層次,可選值有building,systemType,specialty,floor,category,family,familyType， 16 如:desiredHierarchy=specialty,systemtype。 17 customizedNodeKeys: 用來指定篩選樹每個維度用id或者是name作為唯一標識, 如"floor":"id" 18 */ 19 20 // POST https://api.bimface.com/data/v2/files/{fileId}/tree 21 string url = string.Format(BimfaceConstants.API_HOST + "/data/v2/files/{0}/tree?treeType=default", fileId); 22 23 if (!string.IsNullOrWhiteSpace(v)) 24 { 25 url = url + "&v=" + v; 26 } 27 28 string data = string.Empty; 29 if (request != null) 30 { 31 data = request.SerializeToJson(); 32 } 33 34 BimFaceHttpHeaders headers = new BimFaceHttpHeaders(); 35 headers.AddOAuth2Header(accessToken); 36 37 try 38 { 39 SingleModelTree response; 40 41 HttpManager httpManager = new HttpManager(headers); 42 HttpResult httpResult = httpManager.Post(url, data); 43 if (httpResult.Status == HttpResult.STATUS_SUCCESS) 44 { 45 response = httpResult.Text.DeserializeJsonToObject<SingleModelTree>(); 46 } 47 else 48 { 49 response = new SingleModelTree 50 { 51 Message = httpResult.RefText 52 }; 53 } 54 55 return response; 56 } 57 catch (Exception ex) 58 { 59 throw new Exception("[獲取單個模型中構件的默認分類樹]發生異常！", ex); 60 } 61 }
其中調用到的 httpManager.Post() 方法，請參考《C# HTTP系列》
測試：
在BIMFACE的控制台中可以看到我們上傳的文件列表，模型狀態均為轉換成功。
使用“A4.rvt”為例測試上述方法。
完整的分類樹為
success [ { "actualName": "標高 1", "data": null, "elementCount": 4, "id": "311", "items": [ { "actualName": "牆", "data": null, "elementCount": 4, "id": "-2000011", "items": [ { "actualName": "基本牆", "data": null, "elementCount": 4, "id": "", "items": [ { "actualName": "常規 - 200mm", "data": null, "elementCount": 4, "id": "398", "items": [], "name": "常規 - 200mm", "type": "familyType" } ], "name": "基本牆", "type": "family" } ], "name": "牆", "type": "category" } ], "name": "標高 1", "type": "floor" } ]
測試程式碼如下：
// 獲取構件分類樹（默認） protected void btnGetSingleModelTreeByDefault_Click(object sender, EventArgs e) { long fileId = txtFileID.Text.Trim().ToLong(); FileConvertApi api = new FileConvertApi(); SingleModelTree response = api.GetSingleModelTreeByDefault(txtAccessToken.Text, fileId); txtResult.Text = response.Code.ToString2() + Environment.NewLine + response.Message.ToString2() + Environment.NewLine + response.Data.ToStringLine(); }
請求 path(示例)：https://api.bimface.com/data/v2/files/1211223382064960/tree?v=2.0&treeType=customized
請求 header(示例)：“Authorization: Bearer dc671840-bacc-4dc5-a134-97c1918d664b”
請求 body(示例)：
{ "desiredHierarchy": [ "category", "family" ], "customizedNodeKeys": { "category": "name" } }
請求體不能為 NULL ，必須傳遞值。 否則請求失敗，提示 system.error. customized tree request body is null
HTTP響應示例(200)：
{ "code": "success", "message": null, "data": { "items": [ { "actualName": "專用設備", "data": null, "elementCount": 6, "id": "-2001350", "items": [ { "actualName": "投影儀-基於天花板 3D", "data": null, "elementCount": 3, "id": "", "items": [ ], "name": "投影儀-基於天花板 3D", "type": "family" }, { "actualName": "投影螢幕-基於天花板 3D", "data": null, "elementCount": 3, "id": "", "items": [ ], "name": "投影螢幕-基於天花板 3D", "type": "family" } ], "name": "衛浴裝置", "type": "category" } ], "root": "category" } }
返回的結果結構比較複雜，封裝成對應的C#類如下：
/// <summary> /// 獲取單個模型的構件分類樹(自定義樹floor, category, family, familyType)返回的結果類 /// </summary> [Serializable] public class SingleModelTreeByCustomized : GeneralResponse<SingleModelTreeByCustomized> { [JsonProperty("root")] public string Root { get; set; } [JsonProperty("items")] public TreeItem[] Items { get; set; } /// <summary>返回表示當前對象的字元串。</summary> /// <returns>表示當前對象的字元串。</returns> public override string ToString() { return String.Format("[root={0}, items={1}]", Root, Items.ToStringLine()); } }
C#實現方法：
1 /// <summary> 2 /// 獲取單個模型中構件的自定義分類樹 3 /// </summary> 4 /// <param name="accessToken">【必填】令牌</param> 5 /// <param name="fileId">【必填】代表該單模型的文件ID</param> 6 /// <param name="v">【非必填】用來區別treeType為default時返回樹的格式</param> 7 /// <param name="request">【非必填】其他過濾參數類對象</param> 8 /// <returns></returns> 9 public virtual SingleModelTreeByCustomized GetSingleModelTreeByCustomized(string accessToken, long fileId, string v = "2.0", FileTreeRequestBody request = null) 10 { 11 //return GetSingleModelTree(accessToken, fileId, TreeType.Default, v, request); 12 /* 單模型構件分類樹, 13 （1）treeType 接受兩個值：default 和 customized，默認為 default。 14 （2）v 參數用來區別 treeType 為 default 時返回樹的格式, customized 總是返回格式2.0的構件樹。 15 （3）當 treeType 為"customized"時，FileTreeRequestBody 類的 desiredHierarchy 屬性 表示了篩選樹的層次,可選值有building,systemType,specialty,floor,category,family,familyType， 16 如:desiredHierarchy=specialty,systemtype。 17 customizedNodeKeys: 用來指定篩選樹每個維度用id或者是name作為唯一標識, 如"floor":"id" 18 */ 19 20 // POST https://api.bimface.com/data/v2/files/{fileId}/tree 21 string url = string.Format(BimfaceConstants.API_HOST + "/data/v2/files/{0}/tree?treeType=customized", fileId); 22 23 if (!string.IsNullOrWhiteSpace(v)) 24 { 25 url = url + "&v=" + v; 26 } 27 28 string data = string.Empty; 29 if (request != null) 30 { 31 data = request.SerializeToJson(); 32 } 33 34 BimFaceHttpHeaders headers = new BimFaceHttpHeaders(); 35 headers.AddOAuth2Header(accessToken); 36 37 try 38 { 39 SingleModelTreeByCustomized response; 40 41 HttpManager httpManager = new HttpManager(headers); 42 HttpResult httpResult = httpManager.Post(url, data); 43 if (httpResult.Status == HttpResult.STATUS_SUCCESS) 44 { 45 response = httpResult.Text.DeserializeJsonToObject<SingleModelTreeByCustomized>(); 46 } 47 else 48 { 49 response = new SingleModelTreeByCustomized 50 { 51 Message = httpResult.RefText 52 }; 53 } 54 55 return response; 56 } 57 catch (Exception ex) 58 { 59 throw new Exception("[獲取單個模型中構件的自定義分類樹]發生異常！", ex); 60 } 61 }
測試：
同樣使用“A4.rvt”為例測試上述方法。
完整的分類樹為
success [root=單體, items=[actualName=, data=, elementCount=4, id=0, items=[actualName=, data=, elementCount=4, id=0, items=[actualName=, data=, elementCount=4, id=0, items=[actualName=標高 1, data=, elementCount=4, id=311, items=[actualName=牆, data=, elementCount=4, id=-2000011, items=[actualName=基本牆, data=, elementCount=4, id=, items=[actualName=常規 - 200mm, data=, elementCount=4, id=398, items=, name=常規 - 200mm, type=familyType ], name=基本牆, type=family ], name=牆, type=category ], name=標高 1, type=floor ], name=未設專業, type=specialty ], name=未設系統類型, type=systemType ], name=未設單體, type=building ] ]
介面上的篩選樹的層次是過濾條件，主要用於篩選 type 屬性。
測試程式碼如下：
// 獲取構件分類樹（自定義） protected void btnGetSingleModelTreeByCustomized_Click(object sender, EventArgs e) { long fileId = txtFileID.Text.Trim().ToLong(); List<string> lstDesiredHierarchy = new List<string>(); if (chkTreeBuilding.Checked) { lstDesiredHierarchy.Add("building"); } if (chkTreeSystemType.Checked) { lstDesiredHierarchy.Add("systemType"); } if (chkTreeSpecialty.Checked) { lstDesiredHierarchy.Add("specialty"); } if (chkTreeFloor.Checked) { lstDesiredHierarchy.Add("floor"); } if (chkTreeCategory.Checked) { lstDesiredHierarchy.Add("category"); } if (chkTreeFamily.Checked) { lstDesiredHierarchy.Add("family"); } if (chkTreeFamilyType.Checked) { lstDesiredHierarchy.Add("familyType"); } FileTreeRequestBody request = new FileTreeRequestBody(); request.DesiredHierarchy = lstDesiredHierarchy.ToArray();// new[] { "building", "systemType", "specialty", "floor", "category", "family", "familyType" }; request.CustomizedNodeKeys = new Dictionary<string, string> { { "category", "name" } }; FileConvertApi api = new FileConvertApi(); SingleModelTreeByCustomized response = api.GetSingleModelTreeByCustomized(txtAccessToken.Text, fileId, "2.0", request); txtResult.Text = response.Code.ToString2() + Environment.NewLine + response.Message.ToString2() + Environment.NewLine + response.Data; }
