Clash Test Basics

Introduction

Clash detection is used to analyze the potential conflicts between multiple elements in an iModel. Based on criteria you set, it detects geometrical clashes between object element sets and returns information about each of these clashes so you can follow up and determine which might lead to potential problems. In this tutorial, you will learn how to:

• Create a clash test
• Run the clash test against a specific iModel version
• Monitor the Clash Test run process
• Retrieve and interpret the resulting clashes
• Update your clash test

Prerequisites

This tutorial assumes that you already have:

• Access to an iModel and the associated projectId and imodelId for that iModel, along with the named version ID for the version you want to run the test against
• A list of model and category IDs you wish to check for clashes

1. Get a token

To make request to the API a user token is needed. There are several ways to get it.

Implement Authorization Code Flow in the application

---

Follow this article to implement Authorization code workflow in your application.

Grab a user token from Api reference "Try it" Section

---

1. Go here
2. Click "Try it" button.
3. On Authorization section select "AuthorizationCode".
4. After popup closes Authorization header with your user token value should be visible.
5. Save user token value for this tutorial.

2. Create a Clash Test

Now that we have an authorization token, along with the prerequisites we should have everything we need to run our first clash test.

Clash tests are saved and associated with a specific project; if you run a clash test and find issues that you plan to fix in your model, once you upload the new model version you can rerun the same test to ensure they've been resolved.

To create a clash test send an HTTP POST request to POST https://api.bentley.com/clashdetection/tests/

Clash detection tests are highly configurable. so let's quickly go over all of the different parameters you can set in the request body: projectId - Id of the project this test will be associated with.
displayName - Name of the clash test.
description - Additional identifying information or descriptions of the clash.
setA/setB - Object containing clash test information about a given set of elements.
modelIds - Array of model IDs which contain elements to check for clashes.
categoryIds - Array of category IDs which contain elements to check for clashes
selfCheck - Boolean value. When this is true, elements in this set will be checked for clashes against other elements in this set. When false, it will only check against elements in the opposing set.
clearance - When this is set above 0, any elements within this distance will be reported as a clash, even when not touching. A "Clearance" value will be supplied in results, telling you the distance between the elements. This is in meters.
suppressTouching - Boolean value. When this is true, the results will not include elements that are touching, or whose clash overlap falls within the touching tolerance limits specified below.
touchingTolerance - Elements that are overlapping by less than this amount will be suppressed. This is in meters.
includeSubModels - Boolean value. When this is true, any elements under any model that falls under the model hierarchy of the models you've specified will be included. When false, this test will only include elements directly under the models you've specified.

The response from the server will include the id of the newly created test, as well as a link to the test.

3. Run the Clash Detection Test

Now that you have created a test, we're going to go ahead and run it. To run a Clash Detection test, you just need to send the HTTP POST request POST https://api.bentley.com/clashdetection/runs/ with a request body containing the testId from the previous step, the iModel id and Named Version Id you want to run against.

Clash detection tests are asynchronous, so instead of containing the results directly, the result body contains the runId as well as a link to the run. You will use this in the next step to retrieve the run status.

4. Retrieve Clash Detection Results

Once you've run a clash detection test, you'll need to wait for the engine to finish processing the test. This can take less than ten minutes or several hours depending on the queue time and number of elements and potential collision are in your element sets.

There are two parts to results retrieval, retrieving the information about the clash test run itself, and then the actual results:

Retrieve Run Results

---

You can check on the status of your clash job via an HTTP GET https://api.bentley.com/clashdetection/runs/{id} using the runId returned in the previous create step. It can take a while, so you might want to run this on a loop until you get the "status: completed" result.

In addition to the status, the results body will also include some metadata, and most importantly for us a results link we will use to retrieve the actual clash results.

Retrieve Clash Results

---

Using the results link from the previous step, we can now retrieve the actual clash results we've been waiting for using a GET HTTP request GET https://api.bentley.com/clashdetection/results/{id}. The clash results object contains a lot of information, so let's quickly go over them. There are four main array objects in the result body:

categoryList - Category lookup table. Contains an array of category id and category display name pairs.
modelList - Model lookup table. Contains an array of model id and model display name pairs.
suppressingRuleList - Suppression rule lookup table. Contains an array of suppression rule ids and suppression rule display name pairs.
clashDetectionResult - Array of all the clashes in this clash detection result.

A single clash object in the clashDetectionResult array contains:
clashType - The type of clash detected - possible values: Collision, Clearance, Touching, Not Initialized.
clearance - When the clash type is Clearance, the value is returned in meters. Otherwise -1 is returned.
elementAId - The unique id of element A.
elementALabel - The display label of element A.
elementACategoryIndex - The zero-based index used to lookup the element A category in the categoryList.
elementAModelIndex - The zero-based index used to lookup the element A model in the modelList.
elementBId - The unique id of element B.
elementBLabel - The display label of element B.
elementBCategoryIndex - The zero-based index used to lookup the element B category in the categoryList.
elementBModelIndex - The zero-based index used to lookup the element B model in the modelList.
center - The clash center point. This contains x, y, and z properties for the exact spatial position of the center point.
suppressingRuleIndexArray - An array of the zero-based indexes used to lookup any suppression rules this clash would be suppressed by in the suppressingRuleList.

5. Update a Clash Test

After running your test, you might realize you want to tweak your criteria slightly. Instead of making a new test, you can just update the one you just made previously. This is a replacement update, so you will still need the full test criteria you enetered previously. If you still have your test criteria handy, you can just copy it and update as necessary. If not, you can use a GET https://api.bentley.com/clashdetection/tests/{id}, with your test id to retrieve the test details and update from there.

Once you have your test criteria and have implemented any updates you want to make, you can use an HTTP PUT https://api.bentley.com/clashdetection/tests/{id} using the test id.

6. Conclusion

You have now gone through the entire life cycle of a clash detection test: creating, running and retrieving the results. This will aid you in detecting any potential problems or clashes earlier in the modeling process while they are easier to fix. As you continue to practice and gain experience creating and running tests, you will be able to refine the criteria to be specific to your individual needs and issues.

More resources that you may like