Design Element Classification

3D （iModel）分类模型可预测 iModel 中每个几何元素的“类”或类型。每个 iModel 的可用类都是根据“已研究的密钥”选择的。目前，我们支持三种不同的研究键：Category、User Label和 ECClass。例如，如果在 iModel 上运行推理作业，并将类别选为“研究的键”，则 ML 流水线将返回它认为 iModel 中每个元素应如何分类的预测。预测将包含一个可能的匹配列表，每个可能的匹配项都有一个“类置信度”分数。

使用场景

设计元素分类最自然的用例是检测 iModels 中的是否有错误分类。假设管道在源 iModel 中被错误地分类为梁，设计元素分类 ML 模型可以帮助识别有问题的元素，甚至就正确的分类应该是什么提出建议。

输入 : 已创建命名版本的iModel。

输出 : 设计图元分类模型输出两个预测文件 - 一个列出 iModel 中每个图元的所有预测(predictions.json)，另一个仅包含按给定置信度阈值筛选的错误分类图元(misclassifications.json)。

错误分类是指“当前类置信度”低于“预测类置信度”的元素，其中“当前”表示源数据中给出的标签。该值是使用 softmax 函数规范化并相对于 iModel 中的其他类（对于每个元素，每个可能的类的置信度之和等于 1）。因此，在具有许多类似类的 iModels 中，元素可能没有任何具有非常高置信度分数的预测。相反，要查看是否存在强首选，请将最高类置信度与其他类的类置信度进行比较，以查看设计元素分类模型对该选择的相对偏好程度。

所有输出的列表:

EC Instance ID
EC Class Name
Source Model Name
Source Model ID
User Label
Category Label
Category Description
Category ID
Mesh ID: 唯一 3D 网格 ID
Text ID: 唯一文本 ID
Studied Key: 用于将元素组合在一起的列。这些列连接在一起并成为类。当前支持“类别”、“用户标签”或 ECClasses。
Current Class Rank: 根据模型，当前标签的置信度排名位置（{1， ...， N} 中的正整数，其中 N 是类的总数，较低表示更好）。
Current Class Confidence: 模型的置信度，即该类是给定设计元素的正确选择。此置信度分数相对于其他类置信度（越高越好，介于 [0， 1] 之间）
Best Prediction: 根据模型，最佳类的标签。
Predicted Class Confidence: 最佳类置信度（越高越好）。
Classification Confidence: 比较“当前类置信度”和“预测的类置信度”的相对置信度分数（值越高表示模型认为错误分类的可能性越高）。置信度 = 1 - （预测类信任 - 当前类信任）。通常值介于 [0， 1] 之间，因为仅显示错误分类。
接口
教程
其他

API 接口

类型	请求URL	标题	标签
POST	/designelementclassification/runs/{runid}/cancel	取消 Design Element Classification 运行	Design Element Classification
POST	/designelementclassification/runs	创建Design Element Classification 运行	Design Element Classification
DELETE	/designelementclassification/runs/{runid}	删除 Design Element Classification 运行	Design Element Classification
GET	/designelementclassification/models	获取Design Element Classification 相关联的iModel	Design Element Classification
GET	/designelementclassification/runs/{runid}/results/{filename}	获取Design Element Classification 特定结果	Design Element Classification
GET	/designelementclassification/runs/{runid}/results	获取Design Element Classification 所有结果	Design Element Classification
GET	/designelementclassification/runs/{runid}	获取Design Element Classification 运行信息	Design Element Classification
GET	/designelementclassification/runs/{runid}/status	获取Design Element Classification 运行状态	Design Element Classification
GET	/designelementclassification/runs?projectid	获取项目相关的所以Design Element Classification 运行	Design Element Classification

教程

简介

本篇快速入门旨在帮助您了解如何创建设计元素分类推理运行以及如何检索其结果。

在本演练结束时，您将拥有获取任何 iModel 并通过分类管道运行它所需的所有工具。您将熟悉工作流和所涉及的所有 API，并能够将设计元素分类模型集成到 iTwin 驱动的应用程序中。

先决条件

本教程假定您已经创建并配置了：

项目。有关如何创建项目的说明，请参阅此处。如果您有权访问现有项目，则可以使用现有项目。
iModel 已创建。
- 在此处创建新的 iModel。
- 或使用已创建的现有 iModel.
iModel 命名版本。有关如何创建命名版本的说明，可在此处找到。

使用 Design Element Classification API 需要项目级权限。对于这些权限，您必须是拥有给定项目或在项目级别分配了administration_manage_roles权限的组织的组织管理员。如果您对要使用的项目或 iModel 没有管理员访问权限，请联系项目管理员。作为项目管理员，您可以使用管理项目团队成员教程中描述的 API 来创建角色并使用“权限”更新该角色：[“MLRunInference”]。完成此操作并将角色分配给您后，您可以使用项目中的任何 iModel 来完成本教程。

1.注册应用

您需要注册一个应用程序才能使用iTwin平台API。可以使用“注册”按钮自动创建第一个单页应用程序（SPA）。这将允许您为SPA应用程序配置授权代码流并获得正确的访问令牌。

生成后，您将在按钮下显示几行代码

IMJS_AUTH_CLIENT_CLIENT_ID。在应用程序详细信息页面上显示为 Client ID。
IMJS_AUTH_CLIENT_REDIRECT_URI - 指定在用户选择是否对应用进行身份验证后，用户重定向到的位置。在应用程序详细信息页面上显示为 Redirect URI 之一。
IMJS_AUTH_CLIENT_LOGOUT_URI - 指定注销后可将用户返回到的位置。在应用程序详细信息页面上显示为 Post logout redirect URIs 之一。
IMJS_AUTH_CLIENT_SCOPES - 授予应用程序的访问权限列表。在应用程序详细信息页上显示为 Scopes。

[warning] 或者（可选）：按照注册和修改应用程序教程中的说明手动注册和配置应用程序。确保应用程序与Design Element Classification API 相关联，并且启用了scopes: designelementclassification:read designelementclassification:modify。

2.获取token

要对此 API 发出请求，需要有效的用户令牌。有几种方法可以获得。

在应用程序中实现Authorization Code流

按照本文在应用程序中实现授权代码工作流。

[warning] 在这里，您可以使用从上一个应用程序注册步骤生成的 Client ID。

从 Api 参考“Try it”部分获取用户令牌

转到 API 文档。
单击“Try it”按钮。
对于授权部分，请选择“AuthorizationCode”。
登录弹出窗口关闭后，包含用户令牌值的授权标头应该可见。
保存用户令牌值以供以后重复使用。

[warning] 在后续步骤中使用用户令牌替换“JWT_TOKEN”占位符参数。

3.获取可用的设计元素分类模型版本

首先，您需要选择用于推理运行的现有模型版本。若要获取可用版本，请使用“获取设计元素分类模型”终结点。记下 API 响应中的模型版本，以便稍后在本教程的“运行创建”步骤中使用。

Request Syntax

GET https://api.bentley.com/designelementclassification/models HTTP/1.1

Request Headers

Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Headers

Content-Type: application/json

Response Body

{
  "models":[
    {
      "version":"2021.07.07.1",
      "lastModifiedDateTime":"2021-07-20T07:56:20.0428972+00:00"
    },
    {
      "version":"2021.08.08.1",
      "lastModifiedDateTime":"2021-08-20T07:56:20.0428972+00:00"
    }
  ]
}

[warning] 通常，人们会选择最新的模型版本。但是对于向后兼容性，您可以使用较旧的兼容性。

4.创建新的运行

使用创建设计元素分类运行 API 为 changeSetId 指定的提供的 iModel 和命名版本创建并启动新的设计元素分类推理运行。让我们快速浏览一下所有参数：

modelVersion - 从前面的步骤检索到的设计元素分类模型版本。 iModelId - 需要检查分类的iModel。 changeSetId - 需要检查分类的iModel的命名版本的变更集Id。

equest Syntax

POST https://api.bentley.com/designelementclassification/runs HTTP/1.1

Request Headers

Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Request Body

{
  "modelVersion":"2021.06.20.1",
  "iModelId":"466ba62e-2841-4568-89b5-deabf2c6c858",
  "changeSetId":"096f51524e0ed3f088ea298a6833efd1a2285f88"
}

Response Headers

Content-Type: application/json

Response Body

{
  "run":{
    "id":"3a3cb94c-86e1-4359-8caf-25aef1c39e0d",
    "modelVersion":"2021.04.29.4",
    "status":"InProgress",
    "lastModifiedDateTime":"2021-07-20T07:56:20.0428972+00:00",
    "_links":{
      "imodel":{
        "href":"https://api.bentley.com/imodels/ea349f77-f670-4e53-912b-2de45ce824ec"
      },
      "changeSet":{
        "href":"https://api.bentley.com/imodels/ea349f77-f670-4e53-912b-2de45ce824ec/changesets/ee1f94bbf53ee6bc4a524e5580c4e9a4fb49c98e"
      },
      "project":{
        "href":"https://api.bentley.com/projects/41d1720b-c84f-492e-8561-05429610eec6"
      }
    }
  }
}

[warning] 在进程启动时，运行状态可能在短时间内是未启动状态。

[warning] 请注意，在以后的步骤中将需要创建运行时返回的运行 ID。

查询状态

创建运行后，您需要等到运行完成。可以使用 Get Design Element Classification Run Status API 来检查“运行”是否已经完成。

Request Syntax

GET https://api.bentley.com/designelementclassification/runs/RUN_ID/status HTTP/1.1

Request Headers

Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Headers

Content-Type: application/json

Response Body

{
  "status":"NotStarted"
}

Completed - 运行已成功完成。结果已准备就绪，可供使用。
Canceled - 运行已被用户取消。
Failed - 运行未能完成。
NotStarted - 运行已创建，但尚未启动。
InProgress - 运行已创建并已启动。等待完成。

5.检索运行输出

成功完成设计元素分类运行后，可以下载其结果。

获取所有结果

可以使用 Get Design Element Classification Results API 获取所有管道结果。

Request Syntax

GET https://api.bentley.com/designelementclassification/runs/RUN_ID/results HTTP/1.1

Request Headers

Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Headers

Content-Type: application/json

Response Body

{
  "results":[
    {
      "name":"misclassifications.json"
    },
    {
      "name":"metadata.json"
    }
  ]
}

获取结果 若要仅获取特定结果，请使用 Get Design Element Classification Result API。成功后，此终结点将生成 302 Found 响应，并重定向请求以下载所需的文件内容。

Request Syntax

POST https://api.bentley.com/designelementclassification/runs/RUN_ID/results/misclassifications.json HTTP/1.1

Request Headers

Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

6.获取项目中以前的运行

所有设计元素分类运行都与项目相关联。若要获取所有运行的历史记录，可以调用 Get Design Element Classification Runs API。

Request Syntax

GET https://api.bentley.com/designelementclassification/runs?projectId=PROJECT_ID HTTP/1.1

Request Headers

Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Response Headers

Content-Type: application/json

Response Body

{
  "runs":[
    {
      "id":"03adc578-927a-4fbd-b7d7-5622e24397f0",
      "modelVersion":"2021.04.29.4",
      "status":"Finished",
      "metadata":{
        "countOfIssues":0,
        "countOfProcessed":15,
        "countOfElements":15
      },
      "lastModifiedDateTime":"2021-07-20T07:56:20.0428972+00:00",
      "_links":{
        "imodel":{
          "href":"https://api.bentley.com/imodels/IMODEL_ID"
        },
        "changeSet":{
          "href":"https://api.bentley.com/imodels/IMODEL_ID/changesets/CHANGE_SET_ID"
        },
        "project":{
          "href":"https://api.bentley.com/projects/PROJECT_ID"
        }
      }
    }
  ]
}

Run 对象包含一些您可能会发现有用的元数据：

countOfIssues - 使用此设计元素分类模型找到的 iModel 的命名版本中错误分类的元素的计数。
countOfProcessed - 在 iModel 中检查分类的元素计数。
countOfElements - 在 iModel 中找到的元素总数。

7.高级

我们提供了一些额外的 API，可以对分类运行进行更多的控制和管理。

取消运行

设计元素分类运行很复杂，可能需要很长时间才能完成。可以使用Cancel Design Element Classification Run API 取消运行，这样就不必浪费时间等待运行自然失败或在不必要的情况下完成.

Request Syntax

POST https://api.bentley.com/designelementclassification/runs/RUN_ID/cancel HTTP/1.1

Request Headers

Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

删除运行

我们强烈建议删除已取消的运行。您可能还希望清理过时或不必要的历史运行的项目。为此，请使用Delete Design Element Classification Run API。

Request Syntax

DELETE https://api.bentley.com/designelementclassification/runs/RUN_ID HTTP/1.1

Request Headers

Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

[warning] 只能删除已完成的运行。已完成的运行状态：Failed、Canceled、Completed。

结论

恭喜您完成了本教程，此时您应该已经能够为iModel的命名版本创建设计元素分类运行，查询运行状态并最终下载运行结果。结果文件包含有关 iModel 中元素的元数据，如预测类、置信度等。这种元数据可以帮助识别有问题的元素，甚至可以就正确的分类提出建议。

其他

示例代码：https://github.com/iTwin/designelementclassification-api-sample-console-app 更多可查询英文官网文档：https://developer.bentley.com/apis/designelementclassification/overview/

DesignElementClassification 文档说明

Design Element Classification

API 接口

教程

简介

先决条件

1.注册应用

2.获取token

3.获取可用的设计元素分类模型版本

4.创建新的运行

5.检索运行输出

6.获取项目中以前的运行

7.高级

其他

results matching ""

No results matching ""