C#開發BIMFACE系列30 服務端API之模型對比1：發起模型對比
- 2020 年 3 月 3 日
- 筆記
在實際項目中，由於需求變更經常需要對模型文件進行修改。為了便於用戶了解模型在修改前後發生的變化，BIMFACE提供了模型在線對比功能，可以利用在線的模型對比接口，通過簡單的四個步驟實現模型在線對比。模型對比可以對兩個文件/模型進行差異性分析，確定兩個文件/模型之間構件的幾何和屬性差異，包括增加的構件、刪除的構件和修改的構件。 模型對應可以用於進行文件/模型的版本對比。
特別說明：模型對比是在BIMFACE雲端進行的，通常需要5~10分鐘。當模型對比完成後，BIMFACE能通知對比結果。
- 您需要將修改前和修改後的模型上傳到雲端並轉換成功以後才能發起模型對比；
- 目前僅支持.rvt單文件的模型對比。
- 通過服務端API發起模型對比（對比前後模型文件的fileId）；
- 等待雲端對比任務執行；
- 對比完成後，在網頁端通過調用JavaScript API實現差異模型的顯示；
- 除了顯示差異模型，還需要調用服務端API獲取對比結果（包括新增、刪除、修改的構件列表）。
模型文件經過雲端轉換後，生成了BIMFACE定義的數據包。因此，要對比兩個模型文件，實際上需要對比兩個文件的數據包。如下圖所示，文件B是文件A修改後的版本，對比完成之後，其結果包括兩個部分：
- 幾何差異；
- 變更構件及屬性。
對比操作的第一步是調用服務端API發起模型對比。
請求地址：POST https://api.bimface.com/v2/compare
說明：不同版本的模型文件上傳並轉換成功後，即可發起模型對比。由於對比不能立即完成，BIMFace支持在模型對比完成以後，通過Callback機制通知應用；另外，應用也可以通過接口查詢對比狀態。
參數：
請求 path(示例)：https://api.bimface.com/v2/compare
請求 header(示例)：“Authorization: Bearer dc671840-bacc-4dc5-a134-97c1918d664b”
請求 body(示例)：
{ "callback" : "https://api.glodon.com/viewing/callback?authCode=BJ90Jk0affae&signature=2ef131395fb6442eb99abd83d45c2412", "comparedEntityType" : "file", "config" : "object", "followingId" : 22145522, "name" : "compare0001", "previousId" : 12311221, "priority" : 2, "sourceId" : "123223223212" }
HTTP響應示例(200)：
{ "code" : "success", "data" : { "compareId" : 1248756572307264, "createTime" : "2017-12-25 16:17:27", "name" : "compare0001", "priority" : 2, "reason" : "reason", "sourceId" : "123223223212", "status" : "succcess", "thumbnail" : [ "https://m.bimface.com/9b711803a43b92d871cde346b63e5019/thumbnail/96.png" ] }, "message" : "" }
C#實現方法：
1 /// <summary> 2 /// 不同版本的模型文件上傳並轉換成功後，即可發起模型對比。由於對比不能立即完成，BIMFace支持在模型對比完成以後，通過Callback機制通知應用；另外，應用也可以通過接口查詢對比狀態 3 /// </summary> 4 /// <param name="accessToken">【必填】令牌</param> 5 /// <param name="followingId">修改後圖紙(當前本班，本輪)模型文件ID</param> 6 /// <param name="previousId">修改前圖紙(歷史版本，上一輪次)模型文件ID</param> 7 /// <returns></returns> 8 public virtual ModelCompareResponse Compare(string accessToken, long followingId, long previousId) 9 { 10 CompareRequest request = new CompareRequest(followingId, previousId); 11 12 return Compare(accessToken, request); 13 }
其中12行的Compare方法調用了重載方法，實現如下：
1 /// <summary> 2 /// 不同版本的模型文件上傳並轉換成功後，即可發起模型對比。由於對比不能立即完成，BIMFace支持在模型對比完成以後，通過Callback機制通知應用；另外，應用也可以通過接口查詢對比狀態 3 /// </summary> 4 /// <param name="accessToken">【必填】令牌</param> 5 /// <param name="request">對比時的請求參數</param> 6 /// <returns></returns> 7 public virtual ModelCompareResponse Compare(string accessToken, CompareRequest request) 8 { 9 //POST https://api.bimface.com/v2/compare 10 string url = BimfaceConstants.API_HOST + "/v2/compare"; 11 string data = request.SerializeToJson(); 12 13 BimFaceHttpHeaders headers = new BimFaceHttpHeaders(); 14 headers.AddOAuth2Header(accessToken); 15 16 try 17 { 18 ModelCompareResponse response; 19 20 HttpManager httpManager = new HttpManager(headers); 21 HttpResult httpResult = httpManager.Post(url, data); 22 if (httpResult.Status == HttpResult.STATUS_SUCCESS) 23 { 24 response = httpResult.Text.DeserializeJsonToObject<ModelCompareResponse>(); 25 } 26 else 27 { 28 response = new ModelCompareResponse 29 { 30 Message = httpResult.RefText 31 }; 32 } 33 34 return response; 35 } 36 catch (Exception ex) 37 { 38 throw new Exception("[發起模型對比]發生異常！", ex); 39 } 40 }
代碼中使用的 HttpManager 類請參考我的博客文章《C# HTTP系列 HttpWebRequest 與 HttpWebResponse》。
CompareRequest 請求類如下：
1 /// <summary> 2 /// 模型對比請求參數類 3 /// </summary> 4 [Serializable] 5 public class CompareRequest 6 { 7 /// <summary> 8 /// 9 /// </summary> 10 /// <param name="followingId">變更後文件ID，如果為刪除文件，則為null</param> 11 /// <param name="previousId">變更前文件ID，如果為新增文件，則為null</param> 12 /// <param name="name">自定義對比的名稱</param> 13 public CompareRequest(long? followingId, long? previousId, string name = "") 14 { 15 ComparedEntityType = "file"; //要麼賦值，必須是正確的值。如果賦值null，則報錯 16 Config = null; 17 SourceId = null; 18 Priority = 2; 19 CallBack = "http://www.app.com/receive"; 20 21 FollowingId = followingId; 22 PreviousId = previousId; 23 if (name.IsNullOrWhiteSpace()) 24 { 25 Name = DateTime.Now.ToString("yyyyMMddHHmmss") + "對比：" + followingId.ToString2() + "-" + previousId.ToString2(); 26 } 27 } 28 29 /// <summary> 30 /// 對比的模型類型：file 31 /// </summary> 32 [JsonProperty("comparedEntityType", NullValueHandling = NullValueHandling.Ignore)] 33 public string ComparedEntityType { get; set; } 34 35 [JsonProperty("config", NullValueHandling = NullValueHandling.Ignore)] 36 public object Config { get; set; } 37 38 /// <summary> 39 /// 變更後文件ID，如果為刪除文件，則為null 40 /// </summary> 41 [JsonProperty("followingId")] 42 public long? FollowingId { get; set; } 43 44 /// <summary> 45 /// 變更前文件ID，如果為新增文件，則為null 46 /// </summary> 47 [JsonProperty("previousId")] 48 public long? PreviousId { get; set; } 49 50 /// <summary> 51 /// 用戶指定對比後的模型的名字 52 /// </summary> 53 [JsonProperty("name")] 54 public string Name { get; set; } 55 56 /// <summary> 57 /// 第三方應用自己的ID 58 /// </summary> 59 [JsonProperty("sourceId", NullValueHandling = NullValueHandling.Ignore)] 60 public string SourceId { get; set; } 61 62 /// <summary> 63 /// 對比優先級。取值 1、2、3。數字越大，優先級越低。默認為2 64 /// </summary> 65 [JsonProperty("priority")] 66 public int Priority { get; set; } 67 68 /// <summary> 69 /// Callback地址，待轉換完畢以後，BIMFace會回調該地址 70 /// </summary> 71 [JsonProperty("callback")] 72 public string CallBack { get; set; } 73 }
View Code
其中 Name 屬性，在構造函數中默認設置為當前時間 + “對比” + 修改後文件ID + 修改前文件ID。這裡是為了方便使用不需要每次調用該類都給Name賦值，也可以自定義任何有意義的名稱。
ModelCompareResponse 響應類如下：
1 /// <summary> 2 /// 模型對比返回的結果類 3 /// </summary> 4 public class ModelCompareResponse : GeneralResponse<ModelCompareBean> 5 { 6 7 } 8 9 public class ModelCompareBean 10 { 11 /// <summary> 12 /// 對比後返回的ID，用於獲取對比狀態或者結果等信息 13 /// </summary> 14 [JsonProperty("compareId", NullValueHandling = NullValueHandling.Ignore)] 15 public long? CompareId { get; set; } 16 17 /// <summary> 18 /// 對比完成的消耗時間，單位是秒 19 /// </summary> 20 [JsonProperty("cost", NullValueHandling = NullValueHandling.Ignore)] 21 public int? Cost { get; set; } 22 23 /// <summary> 24 /// 對比開始時間，格式：yyyy-MM-dd hh:mm:ss 25 /// </summary> 26 [JsonProperty("createTime", NullValueHandling = NullValueHandling.Ignore)] 27 public string CreateTime { get; set; } 28 29 /// <summary> 30 /// 用戶指定對比後的模型的名字 31 /// </summary> 32 [JsonProperty("name", NullValueHandling = NullValueHandling.Ignore)] 33 public string Name { get; set; } 34 35 /// <summary> 36 /// 離線數據包生成狀態。prepare(未生成); processing(生成中); success(生成成功); failed(生成失敗) 37 /// </summary> 38 [JsonProperty("offlineDatabagStatus", NullValueHandling = NullValueHandling.Ignore)] 39 public string OfflineDatabagStatus { get; set; } 40 41 /// <summary> 42 /// 對比優先級。取值 1、2、3。數字越大，優先級越低。默認為2 43 /// </summary> 44 [JsonProperty("priority", NullValueHandling = NullValueHandling.Ignore)] 45 public int? Priority { get; set; } 46 47 /// <summary> 48 /// 若對比失敗，返回失敗原因 49 /// </summary> 50 [JsonProperty("reason", NullValueHandling = NullValueHandling.Ignore)] 51 public string Reason { get; set; } 52 53 /// <summary> 54 /// 第三方應用自己的ID 55 /// </summary> 56 [JsonProperty("sourceId", NullValueHandling = NullValueHandling.Ignore)] 57 public string SourceId { get; set; } 58 59 /// <summary> 60 /// 對比狀態:prepare（待對比）、processing（對比中）、success（對比成功）、failed（對比失敗） 61 /// </summary> 62 [JsonProperty("status", NullValueHandling = NullValueHandling.Ignore)] 63 public string Status { get; set; } 64 65 /// <summary> 66 /// 對比幾個縮略圖 67 /// </summary> 68 [JsonProperty("thumbnail", NullValueHandling = NullValueHandling.Ignore)] 69 public string[] Thumbnails { get; set; } 70 71 /// <summary> 72 /// 模型對比的類型 rvt(或者igms…) 73 /// </summary> 74 [JsonProperty("type", NullValueHandling = NullValueHandling.Ignore)] 75 public string Type { get; set; } 76 77 /// <summary> 78 /// 處理對比任務的worker類型。model-compare(或者drawing-compare…) 79 /// </summary> 80 [JsonProperty("workerType", NullValueHandling = NullValueHandling.Ignore)] 81 public string WorkerType { get; set; } 82 83 /// <summary>返回表示當前對象的字符串。</summary> 84 /// <returns>表示當前對象的字符串。</returns> 85 public override string ToString() 86 { 87 return this.SerializeToJson(); 88 }
View Code
22在BIMFACE控制台中可以看到我們上傳的文件列表，模型狀態均為轉換成功。
這裡選擇 bimface_2018_mdv_room.rvt 與 Revit案例項目改.0001.rvt 為例來進行對比。
1 /// <summary> 2 /// 開始比對 3 /// </summary> 4 protected void btnStartCompare_Click(object sender, EventArgs e) 5 { 6 txtResult.Text = string.Empty; 7 8 long followingId = lbl1RVT.Text.ToLong(); 9 long previousId = lbl2RVT.Text.ToLong(); 10 11 CompareRequest request = new CompareRequest(followingId, previousId); 12 13 ModelCompareApi api = new ModelCompareApi(); 14 ModelCompareResponse response = api.Compare(txtAccessToken.Text, request); 15 16 txtResult.Text = response.SerializeToJson(); 17 txtCompareID.Text = response.Data.CompareId.ToString(); 18 }
調用對比接口發起對比
返回結果中，code:success表示發起對比成功。到控制台中查看如下，新增了一筆對比記錄。
特別說明：模型對比是在BIMFACE雲端進行的，通常需要5~10分鐘。當模型對比完成後，BIMFACE能通知對比結果。
