系列目录 【已更新最新开发文章，点击查看详细】
在代表模型的源文件上传到BIMFACE后，一般会进行三种API调用操作：
发起模型转换
查询转换状态
如转换成功，获取模型转换后的BIM数据
- 在模型成功进行转换后，模型内的BIM信息会在云端进行解析，抽取并结构化入库。这些信息包含：
-
构件属性信息
构件分类树
楼层
单体
专业
构件材质
模型链接
空间
房间
图纸
…
在确认模型转换成功后，为了开发者能方便的获取这些BIM信息并集成在自己的应用中，BIMFACE提供了一系列的数据接口，这些接口支持两种验权方式：
- Access token： 代表自身应用的身份，使用应用的appkey, secret，通过调用/oauth2/token接口获取。
- View token： 代表对单个模型的访问权限，使用access token，通过调用/view/token以及相关接口获得。
发起转换
请求地址：PUT https://api.bimface.com/translate
说明：源文件上传成功后，即可发起对该文件的转换。由于转换不能立即完成，BIMFace支持在文件转换完成以后，通过Callback机制通知应用；另外，应用也可以通过接口查询转换状态。
参数：application/json 格式
请求 path(示例)：https://api.bimface.com/translate
请求 header(示例)："Authorization: Bearer dc671840-bacc-4dc5-a134-97c1918d664b"
请求 body(示例)：
{
"callback" : "https://api.glodon.com/viewing/callback?authCode=iklJk0affae&signature=2ef131395fb6442eb99abd83d45c3201",
"config" : {
"string" : "string"
},
"priority" : ,
"source" : {
"compressed" : false,
"fileId" : ,
"rootName" : "rootFileName.rvt"
}
}
注意：请求体中的 config 可以设置为空。"config":null 或者传入指定的转换参数 "config":{"texture":true} 。
HTTP响应示例(200)：
{
"code" : "success",
"data" : {
"createTime" : "2017-12-25 17:23:46",
"databagId" : "9b711803a43b92d871cde346b63e5019",
"fileId" : ,
"name" : "bimface_2018.rvt",
"priority" : ,
"reason" : "reason",
"status" : "success",
"thumbnail" : [ "https://m.bimface.com/9b711803a43b92d871cde346b63e5019/thumbnail/96.png", "https://m.bimface.com/9b711803a43b92d871cde346b63e5019/thumbnail/256.png" ]
},
"message" : ""
}
请求体内的参数解释
DGW与RVT格式的文件转换的配置参数不同，所以封装了2个对应的C#类：
/// <summary>
/// 发起DWG文件转化的请求数据
/// </summary>
[Serializable]
public class DwgFileTranslateRequest : FileTranslateRequest
{
/// <summary>
/// Dwg模型转换引擎自定义参数，config参数跟转换引擎相关，不同的转换引擎支持不同的config格式。
/// 例如转换时添加内置材质，则添加参数值{"texture":true}，添加外部材质时参考“使用模型外置材质场景”请求报文。
/// 如果不需要设置该参数，则设置为null
/// </summary>
[JsonProperty("config", NullValueHandling = NullValueHandling.Ignore)]
public DwgModelConfig Config { get; set; }
}
/// <summary>
/// 发起Rvt文件转化的请求数据
/// </summary>
[Serializable]
public class RvtFileTranslateRequest : FileTranslateRequest
{
/// <summary>
/// Rvt模型转换引擎自定义参数，config参数跟转换引擎相关，不同的转换引擎支持不同的config格式。
/// 例如转换时添加内置材质，则添加参数值{"texture":true}，添加外部材质时参考“使用模型外置材质场景”请求报文。
/// 如果不需要设置该参数，则设置为null
/// </summary>
[JsonProperty("config", NullValueHandling = NullValueHandling.Ignore)]
public RvtModelConfig Config { get; set; }
}
/// <summary>
/// 其他三维模型文件，包括RVT格式文转化的请求数据
/// </summary>
[Serializable]
public class Other3DModelFileTranslateRequest : RvtFileTranslateRequest
{
}
[Serializable]
public class TranslateSource
{
public TranslateSource()
{
Compressed = false;
RootName = null;
} /// <summary>
/// 文件Id，即调用上传文件API返回的fileId
/// </summary>
[JsonProperty("fileId")]
public long FileId { get; set; } /// <summary>
/// 是否为压缩文件，默认为false
/// </summary>
[JsonProperty("compressed")]
public bool Compressed { get; set; } /// <summary>
/// 如果是压缩文件，必须指定压缩包中哪一个是主文件。（例如：root.rvt）。
/// 如果不是压缩，则设置为 null
/// </summary>
[JsonProperty("rootName", NullValueHandling = NullValueHandling.Ignore)]
public string RootName { get; set; }
}
共同的基类FileTranslateRequest：
/// <summary>
/// 发起文件转化的请求数据
/// </summary>
[Serializable]
public class FileTranslateRequest
{
public FileTranslateRequest()
{
Priority = ;
CallBack = "http://www.app.com/receive";
} [JsonProperty("source")]
public TranslateSource Source { 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; }
}
不同模型转换支持的自定义参数config：
(1) rvt模型
对应封装成的C#实体类：
/// <summary>
/// rvt 模型配置项
/// </summary>
[Serializable]
public class RvtModelConfig
{
public RvtModelConfig()
{
//设置 null，在序列化的时候忽略该字段，不出现在序列化后的字符串中
Texture = null;
ExportDwg = null;
ExportDrawing = null;
ExportPdf = null;
ViewName = null;
DisplayLevel = null;
ExportDwgInstance = null;
ExportHiddenObjects = null;
ExportSystemType = null;
ExportProperties = null;
Unit = null;
ExportSchedule = null;
} /// <summary>
/// 转换时是否添加材质。默认为 false
/// </summary>
[JsonProperty("texture", NullValueHandling = NullValueHandling.Ignore)]
public bool? Texture { get; set; } /// <summary>
/// rvt2md是否导出dwg文件。默认为 false
/// </summary>
[JsonProperty("exportDwg", NullValueHandling = NullValueHandling.Ignore)]
public bool? ExportDwg { get; set; } /// <summary>
/// dwg2md是否导出mdv(矢量化图纸);取值为true时，exportDwg自动设置为true。默认为 false
/// </summary>
[JsonProperty("exportDrawing", NullValueHandling = NullValueHandling.Ignore)]
public bool? ExportDrawing { get; set; } /// <summary>
/// dwg2md是否导出pdf文件。默认为 false
/// </summary>
[JsonProperty("exportPdf", NullValueHandling = NullValueHandling.Ignore)]
public bool? ExportPdf { get; set; } /// <summary>
/// 转换使用的3D视图。默认为 {3D}
/// </summary>
[JsonProperty("viewName", NullValueHandling = NullValueHandling.Ignore)]
public string ViewName { get; set; } /// <summary>
/// 设置转换的精细度，fine（精细），medium（中等），coarse（粗略）。默认为 fine
/// </summary>
[JsonProperty("displaylevel", NullValueHandling = NullValueHandling.Ignore)]
public string DisplayLevel { get; set; } /// <summary>
/// 是否导出dwg实例。默认为 false
/// </summary>
[JsonProperty("exportDwgInstance", NullValueHandling = NullValueHandling.Ignore)]
public bool? ExportDwgInstance { get; set; } /// <summary>
/// 是否导出三维视图中隐藏的构件。默认为 false
/// </summary>
[JsonProperty("exportHiddenObjects", NullValueHandling = NullValueHandling.Ignore)]
public bool? ExportHiddenObjects { get; set; } /// <summary>
/// 是否在userData中加入mepSystemType。默认为 false
/// </summary>
[JsonProperty("exportSystemType", NullValueHandling = NullValueHandling.Ignore)]
public bool? ExportSystemType { get; set; } /// <summary>
/// 是否在导出NWD的属性db文件。默认为 false
/// </summary>
[JsonProperty("exportProperties", NullValueHandling = NullValueHandling.Ignore)]
public bool? ExportProperties { get; set; } /// <summary>
/// 设置转换使用的单位，取值"ft"\"feet"\"英尺"采用revit默认的英尺为单位，默认以毫米为单位。默认为空
/// </summary>
[JsonProperty("unit", NullValueHandling = NullValueHandling.Ignore)]
public string Unit { get; set; } /// <summary>
/// 是否使用明细表内容。默认为 false
/// </summary>
[JsonProperty("exportSchedule", NullValueHandling = NullValueHandling.Ignore)]
public bool? ExportSchedule { get; set; }
}
Rvt转换配置中很多选项都是有默认值的，如果手动设置的值与默认值相同，那么可以不用设置该项。
为了简化显示请求body中的config配置项，在构造函数中将数值类型的配置项默认设置为 null，再配合 Newtonsoft.Json.dll
[JsonProperty(NullValueHandling = NullValueHandling.Ignore)] 属性，在序列化时可以不生成该项。
(2) dwg模型
对应封装成的C#实体类
/// <summary>
/// dwg 模型配置项
/// </summary>
[Serializable]
public class DwgModelConfig
{
/// <summary>
/// 是否转成矢量图纸，默认为 true
/// </summary>
[JsonProperty("exportDrawing")]
public bool ExportDrawing { get; set; } /// <summary>
/// 是否导出pdf文件，默认为 false
/// </summary>
[JsonProperty("exportPdf")]
public bool ExportPdf { get; set; } /// <summary>
/// 是否导出缩略图，默认为 true
/// </summary>
[JsonProperty("exportThumb")]
public bool ExportThumb { get; set; }
}
下面分别介绍常用的不同类型的文件转换场景
1、DWG文件转换成矢量图纸
请求 body(示例)：
{
"source":{
"fileId":, // 文件ID
"compressed":false // 文件是否为压缩文件
},
"priority":, // 转换优先级
"callback":"http://www.app.com/receive", // 回调地址
"config":null // 转换配置选项
}
C#实现方法：
/// <summary>
/// 发起转换。将DWG文件转换成图片。
/// </summary>
/// <param name="accessToken">令牌</param>
/// <param name="request">DWG文件转化的请求数据对象。根据实际需要设置对象里面的参数，不需要的参数不用赋值</param>
/// <returns></returns>
public virtual FileTranslateResponse TranslateDwgToPicture(string accessToken, DwgFileTranslateRequest request)
{
string data = request.SerializeToJson();
return TranslateFile(accessToken, data);
}
其中调用的 TranslateFile()方法如下：
/// <summary>
/// 发起转换。
/// 源文件上传成功后，即可发起对该文件的转换。由于转换不能立即完成，BIMFace支持在文件转换完成以后，通过Callback机制通知应用；
/// 另外，应用也可以通过接口查询转换状态
/// </summary>
/// <param name="accessToken">令牌</param>
/// <param name="data">请求体数据</param>
/// <returns></returns>
private FileTranslateResponse TranslateFile(string accessToken, string data)
{
//PUT https://api.bimface.com/translate
string url = BimfaceConstants.API_HOST + "/translate"; BimFaceHttpHeaders headers = new BimFaceHttpHeaders();
headers.AddOAuth2Header(accessToken); try
{
FileTranslateResponse response; HttpManager httpManager = new HttpManager(headers);
HttpResult httpResult = httpManager.Put(url, data);
if (httpResult.Status == HttpResult.STATUS_SUCCESS)
{
response = httpResult.Text.DeserializeJsonToObject<FileTranslateResponse>();
}
else
{
response = new FileTranslateResponse
{
Message = httpResult.RefText
};
} return response;
}
catch (Exception ex)
{
throw new Exception("[发起文件转换]发生异常！", ex);
}
}
该方法在后面的几种模型转换中也会用到，是公用的方法。
其中调用到的 httpManager.Put() 方法，请参考《C# HTTP系列》
2、DWG文件转换成图片
请求 body(示例)：
{
"source":{
"fileId":,
"compressed":false,
"rootName":"root.dwg"
},
"priority":,
"callback":"http://www.app.com/receive",
"config":{
"exportDrawing":false // 是否转成矢量图纸
}
}
C#实现方法：
/// <summary>
/// 发起转换。将DWG文件转换成图片。
/// </summary>
/// <param name="accessToken">令牌</param>
/// <param name="request">DWG文件转化的请求数据对象。根据实际需要设置对象里面的参数，不需要的参数不用赋值</param>
/// <returns></returns>
public virtual FileTranslateResponse TranslateDwgToPicture(string accessToken, DwgFileTranslateRequest request)
{
string data = request.SerializeToJson();
return TranslateFile(accessToken, data);
}
3、RVT文件转换成着色模式的效果
请求 body(示例)：
{
"source":{
"fileId":,
"compressed":false,
"rootName":"root.rvt" // 如果是压缩文件，必须指定压缩包中哪一个是主文件
},
"priority":,
"callback":"http://www.app.com/receive",
"config":null
}
C#实现方法：
/// <summary>
/// 发起转换。将RVT文件转换成着色模式的效果。
/// </summary>
/// <param name="accessToken">令牌</param>
/// <param name="request">RVT文件转化的请求数据对象。根据实际需要设置对象里面的参数，不需要的参数不用赋值</param>
/// <returns></returns>
public virtual FileTranslateResponse TranslateRvtToRenderStyle(string accessToken, RvtFileTranslateRequest request)
{
string data = request.SerializeToJson();
return TranslateFile(accessToken, data);
}
4、RVT文件转换成真实模式的效果
请求 body(示例)：
{
"source":{
"fileId":,
"compressed":false,
"rootName":"root.rvt"
},
"priority":,
"callback":"http://www.app.com/receive",
"config":{"texture":true} // 转换时是否添加材质
}
C#实现方法：
/// <summary>
/// 发起转换。将RVT文件转换成真实模式的效果。
/// </summary>
/// <param name="accessToken">令牌</param>
/// <param name="request">RVT文件转化的请求数据对象。根据实际需要设置对象里面的参数，不需要的参数不用赋值</param>
/// <returns></returns>
public virtual FileTranslateResponse TranslateRvtToRealStyle(string accessToken, RvtFileTranslateRequest request)
{
string data = request.SerializeToJson();
return TranslateFile(accessToken, data);
}
5、RVT格式文件转换成具备二三维联动的功能
请求 body(示例)：
{
"source":{
"fileId":,
"compressed":false
},
"priority":,
"config":{
"texture": false, // 转换时是否添加材质
"exportDwg": true, // rvt2md是否导出dwg文件
"exportPdf": true, // dwg2md是否导出pdf文件
"exportDrawing": true // dwg2md是否导出mdv(矢量化图纸);取值为true时，exportDwg自动设置为true
},
"callback":"http://www.app.com/receive"
}
C#实现方法：
/// <summary>
/// 发起转换。将RVT格式文件转换为具备二三维联动的功能效果。
/// </summary>
/// <param name="accessToken">令牌</param>
/// <param name="request">RVT文件转化的请求数据对象。根据实际需要设置对象里面的参数，不需要的参数不用赋值</param>
/// <returns></returns>
public virtual FileTranslateResponse TranslateRvtTo23LinkStyle(string accessToken, RvtFileTranslateRequest request)
{
string data = request.SerializeToJson();
return TranslateFile(accessToken, data);
}
6、其它三维模型文件转换：常规转换（不带材质）
请求 body(示例)：
{
"source":{
"fileId":,
"compressed":false,
"rootName":"root.skp"
},
"priority":,
"callback":"http://www.app.com/receive",
"config":null
}
C#实现方法：
/// <summary>
/// 发起转换。其它三维模型文件转换，常规转换（不带材质）
/// </summary>
/// <param name="accessToken">令牌</param>
/// <param name="request">其他三维模型文件，包括RVT格式文件转化的请求数据对象。根据实际需要设置对象里面的参数，不需要的参数不用赋值</param>
/// <returns></returns>
public virtual FileTranslateResponse TranslateOther3DModelToWithoutMaterialStyle(string accessToken, Other3DModelFileTranslateRequest request)
{
string data = request.SerializeToJson();
return TranslateFile(accessToken, data);
}
7、其他三维模型文件包括RVT格式文件，需要转换出引用的外部材质场景、贴图等
请求 body(示例)：
{
"source":{
"fileId":,
"compressed":true,
"rootName":"bimface_2018_打包材质&系统材质库.rvt"
},
"priority":,
"callback":"http://www.app.com/receive",
"config":{"texture":true}
}
C#实现方法：
/// <summary>
/// 发起转换。
/// 其他三维模型文件包括RVT格式文件，需要转换出引用的外部材质场景、贴图等
/// （上传的文件必须为压缩包，压缩包内同级目录包含模型文件和关联的所有材质文件，转换时必须指定rootName为主文件）。
/// </summary>
/// <param name="accessToken">令牌</param>
/// <param name="request">其他三维模型文件，包括RVT格式文件转化的请求数据对象。根据实际需要设置对象里面的参数，不需要的参数不用赋值</param>
/// <returns></returns>
public virtual FileTranslateResponse TranslateOther3DModelToWithMaterialStyle(string accessToken, Other3DModelFileTranslateRequest request)
{
string data = request.SerializeToJson();
return TranslateFile(accessToken, data);
}
测试
在BIMFACE的控制台中可以看到我们上传的文件列表，共计2个文件。
下面以 rac_advanced_sample_project-三维视图 - From Parking Area.dwg 文件为例，测试“将DWG文件转换成矢量图纸”方法。
在如下所示的测试页面中，DWG文件转换区域中，选择相关的转换参数，然后点击【将DWG文件转换成矢量图纸】按钮开始转换
刷新控制台中的列表可以看到该文件的模型状态显示为“转换中”
等待几秒或者几分钟后，该文件的模型状态显示为“转换成功”
待BIMFace转换完毕后，根据应用传入的回调地址，BIMFace会通知转换结果，转换可能成功、也可能失败。
查看服务器上配置的Callback处理程序记录的日志：
Callback的配置与业务逻辑
Callback的配置项如下：
Callback机制与微信开发需要开发者提供开发者服务器的原理类似，用于开发者与第三方(BIMFACE、微信登)平台进行数据的回传与逻辑的交互。在ASP.NET开发模式下一般可以采取以下几种方式来设置：
方式1：使用一般处理程序(.ashx) 处理业务逻辑的交互。
方式2：建立 ASP.NET WebForm 程序，在具体的 WebForm 页面的构造函数中处理业务逻辑的交互。
方式3：建立 ASP.NET MVC，通过控制器处理业务逻辑的交互。
方式4：建立 ASP.NET 程序，通过 WebAPI 处理业务逻辑的交互。
本示例种采用了第一种方式。
Callback 传回以下参数：
signature（签名）：为了确保回调消息是由BIMFace发出的，应用在收到回调消息后，须验证签名。签名的计算方式：MD5(``appKey:appSecret:fileId:status:nonce'')，如果应用计算的签名与BIMFace返回的签名一致，则证明该消息是安全可靠的。
应用收到回调后，须向BIMFace发送回执，回执消息：HTTP STATUS 200
BimFaceHandler的回调地址对应的完整逻辑方法如下：
/// <summary>
/// BimFaceHandler 的摘要说明
/// </summary>
public class BimFaceHandler : IHttpHandler
{
public void ProcessRequest(HttpContext context)
{
context.Response.ContentType = "text/plain";
//context.Response.Write("Hello World"); string appKey = ConfigUtility.GetAppSettingValue("BIMFACE_AppKey");
string appSecret = ConfigUtility.GetAppSettingValue("BIMFACE_AppSecret");
string uid = context.Request.QueryString["uid"]; // SparkBimFace #region 校验
if (appKey.IsNullOrWhiteSpace())
{
LogUtility.Error("BIMFace appKey 配置项没有配置！"); return;
} if (appSecret.IsNullOrWhiteSpace())
{
LogUtility.Error("BIMFace appSecret 配置项没有配置！"); return;
} if (uid.IsNullOrWhiteSpace())
{
LogUtility.Error("[非法请求]回调地址Url链接中的参数 uid 没有配置或者配置的值为空！"); return;
}
#endregion long fileId = context.Request.QueryString["fileId"].ToLong(); // 文件ID
string status = context.Request.QueryString["status"]; // 转换的结果
string reason = context.Request.QueryString["reason"]; // 若转换失败，则返回失败原因
string thumbnail = context.Request.QueryString["thumbnail"]; // 缩略图地址
string nonce = context.Request.QueryString["nonce"]; // 回调随机数
string signature = context.Request.QueryString["signature"]; // BIMFACE的加密签名 string callbackResponse = string.Format("fileId:{0},\r\nstatus:{1},\r\nreason:{2},\r\nthumbnail:{3},\r\nnonce:{4},\r\nsignature:{5}",
fileId, status, reason, thumbnail, nonce, signature);
string tip;
string custCalcSignature;
FileConvertApi api = new FileConvertApi();
bool checkSignature = api.CheckCallbackSignature(appKey, appSecret, fileId, status, nonce, signature, out custCalcSignature);
if (checkSignature)
{
tip = "[BIMFace发出的回调信息签名验证成功！]"
+ Environment.NewLine
+ callbackResponse;
LogUtility.Info(tip); //Todo 此处可以根据fileId把相关的信息写入数据库中 // 回执消息：应用收到回调后，须向BIMFace发送回执，回执消息：HTTP STATUS 200
context.Response.Write("HTTP STATUS 200");
}
else
{
tip = "[BIMFace发出的回调信息签名验证不通过！]"
+ Environment.NewLine
+ callbackResponse
+ Environment.NewLine
+ "自定义计算签名 custCalcSignature：" + custCalcSignature; LogUtility.Error(tip); context.Response.Write(tip);
} context.Response.End();
} /// <summary>
/// 该属性获得一个布尔值，指示另一个请求是否可以使用该HTTP处理程序的实例。
/// <para>如果设置为true，能提高性能，但要注意线程之间安全性问题。如果设置为false，则线程是安全的</para>
/// </summary>
public bool IsReusable
{
get
{
return false;
}
}
}
其中调用到的 CheckCallbackSignature()方法，用于验证BIMFace发出的回调消息签名信息是否安全可靠
/// <summary>
/// 验证BIMFace发出的回调消息签名信息是否安全可靠
/// </summary>
/// <param name="appKey">开发者秘钥</param>
/// <param name="appSecret">开发者密码</param>
/// <param name="fileId">BIMFace发出的回调信息：文件ID</param>
/// <param name="status">BIMFace发出的回调信息：转换的结果</param>
/// <param name="nonce">BIMFace发出的回调信息：回调随机数</param>
/// <param name="signature">BIMFace发出的回调信息：签名</param>
/// <param name="custCalcSignature">输出参数：根据BIMFACE平台的加密规则计算出来的签名信息</param>
/// <returns></returns>
public bool CheckCallbackSignature(string appKey, string appSecret, long fileId, string status, string nonce, string signature, out string custCalcSignature)
{
custCalcSignature = GetCallbackSignature(appKey, appSecret, fileId, status, nonce); return custCalcSignature == signature;
}
/// <summary>
/// 获取BIMFace发出的回调消息签名信息
/// </summary>
/// <param name="appKey">开发者秘钥</param>
/// <param name="appSecret">开发者密码</param>
/// <param name="fileId">BIMFace发出的回调信息：文件ID</param>
/// <param name="status">BIMFace发出的回调信息：转换的结果</param>
/// <param name="nonce">BIMFace发出的回调信息：回调随机数</param>
/// <returns></returns>
public string GetCallbackSignature(string appKey, string appSecret, long fileId, string status, string nonce)
{
/* signature（签名）：为了确保回调消息是由BIMFace发出的，应用在收到回调消息后，须验证签名。
* 签名的计算方式：MD5("appKey:appSecret:fileId:status:nonce")，如果应用计算的签名与BIMFace返回的签名一致，则证明该消息是安全可靠的。
*/ return string.Format("{0}:{1}:{2}:{3}:{4}", appKey, appSecret, fileId, status, nonce).EncryptByMD5();
}
这里使用C#的自定义扩展方法 EncryptByMD5()
/// <summary>
/// 使用 MD5(不可逆加密) 算法加密字符串
/// </summary>
/// <param name="this">扩展对象。字符串</param>
/// <param name="caseType">字符串大小写。默认小写</param>
/// <returns></returns>
public static string EncryptByMD5(this string @this, CaseType caseType = CaseType.Lower)
{
using (MD5 md5 = MD5.Create())
{
var sb = new StringBuilder();
byte[] hashBytes = md5.ComputeHash(Encoding.Default.GetBytes(@this));
foreach (byte bytes in hashBytes)
{
sb.Append(bytes.ToString("X2"));//X2 表示二进制
} return caseType == CaseType.Upper ? sb.ToString() : sb.ToString().ToLower();
}
}
系列目录 【已更新最新开发文章，点击查看详细】