Clash Detection Viewport API

The Clash Detection Viewport extension (included in the Clash Detection Bundle extension) displays meshes that are detected to be in clash (both soft and hard clash) and duplicate meshes. It handles both the main viewport and the additional clash viewport that can be optionally enabled.

When a clash result row is clicked in the Clash Detection Results list, the main viewport will modify the camera position to center it on the clash area (if it exists).

Clash Viewport Menu

The Clash Viewport menu button is located in the top right corner of the main and clash viewports. Clicking it will open the menu that contains the following settings:

Note

Settings are shared between the two viewports.

Clash Mesh

• Use source normals: Uses source normals when building the clash meshes (only used if “Use Selection Groups” is disabled).

• Wireframe thickness: Thickness of the wireframe.

Clash outlines

• Outline min scale: Minimum scale of the outline. Below this value the outline will not be displayed.

• Outline max thickness: Maximum thickness of the outline in world units. Above this value outline thickness will be clamped.

• Outline max segments: Maximum number of segments of the outline. Above this value outline will be simplified.

Camera

• Re-centering far tolerance: Positive tolerance that will prevent camera from being re-centered (from current position) when selecting a clash.

• Re-centering near tolerance: Negative tolerance that will prevent camera from being re-centered (from current position) when selecting a clash.

Note

Set both tolerances to 0 to always re-center no matter the distance.

Main Viewport

• Show clash Meshes: When enabled, the clash meshes will be displayed in the main viewport.

• Show clash outlines: When enabled, the clash outlines will be displayed in the main viewport.

• Use Selection Groups: When enabled, the original source meshes will be put into a custom selection group to show them as an overlay over the original meshes. This is useful to see through occluded objects.

Clash Viewport

• Show meshes and outlines: When enabled, the meshes and outlines will be displayed in the clash viewport.

• Use Translucent Materials: When enabled the meshes will be displayed with a transparent material to avoid occluding the clash profile.

Advanced

• Max displayed clashes: The maximum number of clashes to display in the main and clash viewports. Only obeyed when ‘Show clash meshes’ is disabled or ‘Use selection groups’ is enabled.

• Viewport Debug Mode: When enabled, some debug information will be printed in the console.

Camera Centering

The clash viewport automatically centers the camera on the clash area when a clash is selected.

The camera re-centering follows this logic:

• If there is a valid outline larger than Outline min scale, the camera will be centered on the outline.

• If there is no valid outline, the camera will be centered on one of the two clashing meshes.

  • A mesh is considered “smaller” than another if the squared sum of its bounding box sides is three times smaller than the same calculation for the other mesh.

  • If Use Selection Groups is enabled, the camera will be centered on the smallest source mesh (the original mesh that has been marked as clashing).

  • If Use Selection Groups is disabled, the camera will be centered on the smallest clash mesh (mesh composed of the polygons that are in clash with the other mesh).

Performance

The performance of the clash detection viewport is affected by the following factors:

• Stage size in number of meshes

• Stage size in number of polygons

• Complexity of the meshes (in terms of generated overdraw when using Translucent Materials)

• Console warnings (and file logging)

When experiencing freezing for extended periods of time, consider the following:

• Large stages can cause performance issues when Use Selection Groups is disabled.

• Some stages that are incorrectly exported can print hundreds of thousands of warnings to the console (and in the log) that can affect performance.

  • Disable Show clash outlines and leave Use Selection Groups enabled to avoid any kind of USD recomposition when switching results.

  • Disable Show clash meshes, Show clash outlines and Show meshes and outlines to remove all visualization in both viewports.

• Disabling and re-enabling some options will cause detach and re-attach of the clash session Layer.

  • Consider changing the options before loading the stage to avoid any performance issues.

When experiencing low FPS performance, consider the following:

• For some large meshes, the translucent material can affect performance.

  • Consider disabling the corresponding option in the Clash Viewport menu if needed.

Visualization

After clicking on a clash, the two meshes will change their appearance in the main viewport. The two clashing meshes will be displayed in isolation from the rest of the stage also in the Clash Detection Viewport (if enabled). The appearance of the meshes will depend on the settings of the Clash Viewport menu.

Note

The appearance of the meshes will be restored when deselecting a clash.

Use Selection Groups Enabled (Default)

When using Selection Groups:

• The original source meshes will be put into a custom selection group to show them as an overlay over the original meshes. This is useful to see through occluded objects.

• Clash intersection profile will be shown in light-independent (emissive) purple.

Hard Clash Before

Hard Clash After

Use Selection Groups Disabled

For Soft and Hard Clashes:

• The two meshes of the clash will be displayed using different colors (light blue and light orange).

• Non-clashing polygons composing the mesh will be drawn:

  • Main Viewport: non-clashing polygons will be shown with a flat shaded look.

  • Clash Viewport: non-clashing polygons will be shown with a transparent material to avoid occluding the clash profile.

• Clashing polygons composing the mesh will be drawn:

  • Main Viewport: clashing polygons will be shown with an overlapping black wireframe and a light-independent look (emissive).

  • Clash Viewport: clashing polygons will be shown with non-transparent diffuse material.

For Hard Clashes Only:

• Clash intersection profiles will be shown in light-independent (emissive) purple.

Hard Clash Before

Hard Clash After

Soft Clash Before

Soft Clash After

For Duplicates:

• Duplicated meshes will be displayed using light blue with overlapped wireframe.

• If the first duplicated mesh is missing, the duplicate will be shown in orange.

Detected Duplicate Before

Detected Duplicate After

Moving Clash Meshes

Moving clash meshes in the stage is useful to clearly see the issue in a crowded area. Some rules to keep in mind when moving clash meshes, as the behavior is different for instanced prims vs. non-instanced prims:

When Clash Meshes are shown for non-instanced prims, the original source meshes are modified.

This means that:

• Translating Clash Meshes for non-instanced prims in main viewport moves the original source mesh that has been marked as clashing.

• Translating Clash Meshes for non-instanced prims in clash viewport does not affect the original source mesh that has been marked as clashing.

• Deselecting a clash from the Clash Detection list of clashes will restore original look of the source mesh.

Moving Clash Mesh

Source mesh is moved too

When Clash Meshes are shown for instanced prims, the original source meshes are hidden.

This means that:

• Translating Clash Meshes in either viewport does not affect the original source mesh that has been marked as clashing.

• Deselecting a clash from the Clash Detection list of clashes will restore visibility of the original source mesh.

Moved Clash Mesh (INSTANCING)

Clash Mesh restored back to its original position

Warnings

The Clash Viewport will display yellow warnings when the meshes have been modified since the last clash detection run. If needed, re-run the clash detection to refresh and update results to avoid these warnings.

The following conditions will cause warnings:

• If one of the two (or both) original source meshes have been deleted from the stage or layer

• If one of the two (or both) original source meshes have been moved from their original location

• If both source meshes for a duplicate have been deleted from the stage or layer

• If one of the two (or both) source duplicate meshes have been moved from their original location

Removing Clash Mesh A

Removing Clash Mesh B

Removing Clash Mesh A and B

Moving Clash Mesh A

Moving Clash Mesh B

Dynamic Clashes

To visualize dynamic clashes, it is better to use the Clash Detection Bake API (BETA) extension to bake dynamic clashes.

If this is not possible, there are some limitations to keep in mind when using the Clash Detection Viewport API:

• When Use selection groups is enabled, the meshes will follow the animation of the original meshes.

• When Use selection groups is disabled, the meshes will not follow the animation of the original meshes.

• The outlines will not be updated in any case.

• The Clash Detection Viewport will not be updated in any case.

• Double clicking on a clash result will show the dedicated dynamic clash slider (see Clash Detection UI) that will update both viewports.

• Alternatively, you can use the Inspect Clashing Frames on Timeline option in the contextual menu of a clash result (see Clash Detection UI).

API Reference

ClashDetectionViewportAPI Class

class ClashDetectionViewportAPI(clash_viewport: ClashDetectionViewport)

A class to manage and control the clash detection viewport.

This class provides functionality to display and manage clash meshes in both the main viewport and a dedicated clash detection viewport.

Parameters:

clash_viewport (ClashDetectionViewport) – An instance of ClashDetectionViewport to manage clashes.

Methods

hide_all_clash_meshes() → None

Removes all clash meshes from main viewport or clash viewport.

display_clashes_at_timecode(

clash_timecode: float,

clash_info_items: Dict[str, Any],

display_clash_in_main_viewport: bool = True,

display_clash_in_clash_viewport: bool = True,

center_main_viewport_on_clash: bool = True,

center_clash_viewport_on_clash: bool = True,

center_main_viewport_fine_tuning: bool = True,

center_clash_viewport_fine_tuning: bool = True,

) → None

Displays a set of clashes at a specific timecode in main and/or dedicated clash viewport.

Parameters:

• clash_timecode (float) – Timecode at which the clash meshes should be displayed.

• clash_info_items (Dict[str, Any]) – Dictionary of ClashInfo to be displayed.

• display_clash_in_main_viewport (bool) – If True, displays clash meshes in the main viewport.

• display_clash_in_clash_viewport (bool) – If True, displays clash meshes in the dedicated clash viewport.

• center_main_viewport_on_clash (bool) – If True, centers active camera on the clashes in the main viewport.

• center_clash_viewport_on_clash (bool) – If True, centers active camera on the clashes in the clash viewport.

• center_main_viewport_fine_tuning (bool) – If True, avoids re-centering the camera in main viewport for small movements.

• center_clash_viewport_fine_tuning (bool) – If True, avoids re-centering the camera in clash viewport for small movements.

Properties

property clash_viewport_window

Gets the ViewportWindow handle to dedicated Clash Detection Viewport.

Returns:

The handle to the dedicated Clash Detection Viewport window.

Return type:

ViewportWindow | None

Getting the API Instance

get_api_instance() → ClashDetectionViewportAPI

Retrieve the singleton instance of ClashDetectionViewportAPI.

Returns:

The singleton instance of the ClashDetectionViewportAPI.

Return type:

ClashDetectionViewportAPI

Example Usage

from omni.physxclashdetectionviewport import get_api_instance

def display_clash_by_clash_info(self, clash_infos: Sequence[ClashInfo], timecode: float):
    # Get the API instance
    viewport_api = get_api_instance()

    clash_info_items = {}
    for item in clash_infos:
        clash_info_items[item.overlap_id] = item

    # Display clashes at a specific timecode
    viewport_api.display_clashes_at_timecode(
        clash_timecode=timecode,
        clash_info_items=clash_info_items,
        display_clash_in_main_viewport=True,
        display_clash_in_clash_viewport=True,
        center_main_viewport_on_clash=True,
        center_clash_viewport_on_clash=True
    )

    # Hide all clash meshes
    viewport_api.hide_all_clash_meshes()

    # Access the clash viewport window
    clash_window = viewport_api.clash_viewport_window