C#开发BIMFACE系列30 服务端API之模型对比1：发起模型对比

系列目录     【已更新最新开发文章，点击查看详细】

　　在实际项目中，由于需求变更经常需要对模型文件进行修改。为了便于用户了解模型在修改前后发生的变化，BIMFACE提供了模型在线对比功能，可以利用在线的模型对比接口，通过简单的四个步骤实现模型在线对比。模型对比可以对两个文件/模型进行差异性分析，确定两个文件/模型之间构件的几何和属性差异，包括增加的构件、删除的构件和修改的构件。 模型对应可以用于进行文件/模型的版本对比。

特别说明：模型对比是在BIMFACE云端进行的，通常需要5~10分钟。当模型对比完成后，BIMFACE能通知对比结果。

前置条件

• 您需要将修改前和修改后的模型上传到云端并转换成功以后才能发起模型对比；
• 目前仅支持.rvt单文件的模型对比。

基本步骤

1. 通过服务端API发起模型对比（对比前后模型文件的fileId）；
2. 等待云端对比任务执行；
3. 对比完成后，在网页端通过调用JavaScript API实现差异模型的显示；
4. 除了显示差异模型，还需要调用服务端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#实现方法：

/// <summary>
///  不同版本的模型文件上传并转换成功后，即可发起模型对比。由于对比不能立即完成，BIMFace支持在模型对比完成以后，通过Callback机制通知应用；另外，应用也可以通过接口查询对比状态
/// </summary>
/// <param name="accessToken">【必填】令牌</param>
/// <param name="followingId">修改后图纸(当前本班，本轮)模型文件ID</param>
/// <param name="previousId">修改前图纸(历史版本，上一轮次)模型文件ID</param>
/// <returns></returns>
public virtual ModelCompareResponse Compare(string accessToken, long followingId, long previousId)
{
    CompareRequest request = new CompareRequest(followingId, previousId);

    return Compare(accessToken, request);
}

其中12行的Compare方法调用了重载方法，实现如下：

/// <summary>
///  不同版本的模型文件上传并转换成功后，即可发起模型对比。由于对比不能立即完成，BIMFace支持在模型对比完成以后，通过Callback机制通知应用；另外，应用也可以通过接口查询对比状态
/// </summary>
/// <param name="accessToken">【必填】令牌</param>
/// <param name="request">对比时的请求参数</param>
/// <returns></returns>
public virtual ModelCompareResponse Compare(string accessToken, CompareRequest request)
{
    //POST https://api.bimface.com/v2/compare
    string url = BimfaceConstants.API_HOST + "/v2/compare";
    string data = request.SerializeToJson();

    BimFaceHttpHeaders headers = new BimFaceHttpHeaders();
    headers.AddOAuth2Header(accessToken);

    try
    {
        ModelCompareResponse response;

        HttpManager httpManager = new HttpManager(headers);
        HttpResult httpResult = httpManager.Post(url, data);
        if (httpResult.Status == HttpResult.STATUS_SUCCESS)
        {
            response = httpResult.Text.DeserializeJsonToObject<ModelCompareResponse>();
        }
        else
        {
            response = new ModelCompareResponse
            {
                Message = httpResult.RefText
            };
        }

        return response;
    }
    catch (Exception ex)
    {
        throw new Exception("[发起模型对比]发生异常！", ex);
    }
}

代码中使用的 HttpManager 类请参考我的博客文章《C# HTTP系列 HttpWebRequest 与 HttpWebResponse》。

CompareRequest 请求类如下：

/// <summary>
///     模型对比请求参数类
/// </summary>
[Serializable]
public class CompareRequest
{
    /// <summary>
    /// 
    /// </summary>
    /// <param name="followingId">变更后文件ID，如果为删除文件，则为null</param>
    /// <param name="previousId">变更前文件ID，如果为新增文件，则为null</param>
    /// <param name="name">自定义对比的名称</param>
    public CompareRequest(long? followingId, long? previousId, string name = "")
    {
        ComparedEntityType = "file"; //要么赋值，必须是正确的值。如果赋值null，则报错
        Config = null;
        SourceId = null;
        Priority = 2;
        CallBack = "http://www.app.com/receive";

        FollowingId = followingId;
        PreviousId = previousId;
        if (name.IsNullOrWhiteSpace())
        {
            Name = DateTime.Now.ToString("yyyyMMddHHmmss") + "对比：" + followingId.ToString2() + "-" + previousId.ToString2();
        }
    }

    /// <summary>
    ///     对比的模型类型：file
    /// </summary>
    [JsonProperty("comparedEntityType", NullValueHandling = NullValueHandling.Ignore)]
    public string ComparedEntityType { get; set; }

    [JsonProperty("config", NullValueHandling = NullValueHandling.Ignore)]
    public object Config { get; set; }

    /// <summary>
    ///     变更后文件ID，如果为删除文件，则为null
    /// </summary>
    [JsonProperty("followingId")]
    public long? FollowingId { get; set; }

    /// <summary>
    ///     变更前文件ID，如果为新增文件，则为null
    /// </summary>
    [JsonProperty("previousId")]
    public long? PreviousId { get; set; }

    /// <summary>
    ///     用户指定对比后的模型的名字
    /// </summary>
    [JsonProperty("name")]
    public string Name { get; set; }

    /// <summary>
    ///     第三方应用自己的ID
    /// </summary>
    [JsonProperty("sourceId", NullValueHandling = NullValueHandling.Ignore)]
    public string SourceId { get; set; }

    /// <summary>
    ///     对比优先级。取值 1、2、3。数字越大，优先级越低。默认为2
    /// </summary>
    [JsonProperty("priority")]
    public int Priority { get; set; }

    /// <summary>
    ///     Callback地址，待转换完毕以后，BIMFace会回调该地址
    /// </summary>
    [JsonProperty("callback")]
    public string CallBack { get; set; }
}

其中 Name 属性，在构造函数中默认设置为当前时间 + "对比" + 修改后文件ID + 修改前文件ID。这里是为了方便使用不需要每次调用该类都给Name赋值，也可以自定义任何有意义的名称。

ModelCompareResponse 响应类如下：

/// <summary>
    ///  模型对比返回的结果类
    /// </summary>
    public class ModelCompareResponse : GeneralResponse<ModelCompareBean>
    {

    }

    public class ModelCompareBean
    {
        /// <summary>
        /// 对比后返回的ID，用于获取对比状态或者结果等信息
        /// </summary>
        [JsonProperty("compareId", NullValueHandling = NullValueHandling.Ignore)]
        public long? CompareId { get; set; }

        /// <summary>
        ///  对比完成的消耗时间，单位是秒
        /// </summary>
        [JsonProperty("cost", NullValueHandling = NullValueHandling.Ignore)]
        public int? Cost { get; set; }

        /// <summary>
        /// 对比开始时间，格式：yyyy-MM-dd hh:mm:ss
        /// </summary>
        [JsonProperty("createTime", NullValueHandling = NullValueHandling.Ignore)]
        public string CreateTime { get; set; }

        /// <summary>
        /// 用户指定对比后的模型的名字
        /// </summary>
        [JsonProperty("name", NullValueHandling = NullValueHandling.Ignore)]
        public string Name { get; set; }

        /// <summary>
        ///  离线数据包生成状态。prepare(未生成); processing(生成中); success(生成成功); failed(生成失败)
        /// </summary>
        [JsonProperty("offlineDatabagStatus", NullValueHandling = NullValueHandling.Ignore)]
        public string OfflineDatabagStatus { get; set; }

        /// <summary>
        /// 对比优先级。取值 1、2、3。数字越大，优先级越低。默认为2
        /// </summary>
        [JsonProperty("priority", NullValueHandling = NullValueHandling.Ignore)]
        public int? Priority { get; set; }

        /// <summary>
        ///  若对比失败，返回失败原因
        /// </summary>
        [JsonProperty("reason", NullValueHandling = NullValueHandling.Ignore)]
        public string Reason { get; set; }

        /// <summary>
        ///  第三方应用自己的ID
        /// </summary>
        [JsonProperty("sourceId", NullValueHandling = NullValueHandling.Ignore)]
        public string SourceId { get; set; }

        /// <summary>
        ///  对比状态:prepare（待对比）、processing（对比中）、success（对比成功）、failed（对比失败）
        /// </summary>
        [JsonProperty("status", NullValueHandling = NullValueHandling.Ignore)]
        public string Status { get; set; }

        /// <summary>
        ///  对比几个缩略图
        /// </summary>
        [JsonProperty("thumbnail", NullValueHandling = NullValueHandling.Ignore)]
        public string[] Thumbnails { get; set; }

        /// <summary>
        /// 模型对比的类型 rvt(或者igms…​)
        /// </summary>
        [JsonProperty("type", NullValueHandling = NullValueHandling.Ignore)]
        public string Type { get; set; }

        /// <summary>
        /// 处理对比任务的worker类型。model-compare(或者drawing-compare…​)
        /// </summary>
        [JsonProperty("workerType", NullValueHandling = NullValueHandling.Ignore)]
        public string WorkerType { get; set; }

        /// <summary>返回表示当前对象的字符串。</summary>
        /// <returns>表示当前对象的字符串。</returns>
        public override string ToString()
        {
            return this.SerializeToJson();
        }

测试

22在BIMFACE控制台中可以看到我们上传的文件列表，模型状态均为转换成功。

这里选择 bimface_2018_mdv_room.rvt 与 Revit案例项目改.0001.rvt 为例来进行对比。

/// <summary>
///  开始比对
/// </summary>
protected void btnStartCompare_Click(object sender, EventArgs e)
{
    txtResult.Text = string.Empty;

    long followingId = lbl1RVT.Text.ToLong(); 
    long previousId = lbl2RVT.Text.ToLong(); 

    CompareRequest request = new CompareRequest(followingId, previousId);

    ModelCompareApi api = new ModelCompareApi();
    ModelCompareResponse response = api.Compare(txtAccessToken.Text, request);

    txtResult.Text = response.SerializeToJson();
    txtCompareID.Text = response.Data.CompareId.ToString();
}

调用对比接口发起对比

 返回结果中，code:success表示发起对比成功。到控制台中查看如下，新增了一笔对比记录。

特别说明：模型对比是在BIMFACE云端进行的，通常需要5~10分钟。当模型对比完成后，BIMFACE能通知对比结果。

在下一篇《C#开发BIMFACE系列31 服务端API之模型对比2：获取模型对比状态》中详细介绍如何获取模型对比状态。

系列目录     【已更新最新开发文章，点击查看详细】