Is this page helpful?

clash_detect#

This module provides the main clash detection functionality for USD stages.

Classes#

ClashDetection#

class omni.physxclashdetectioncore.clash_detect.ClashDetection#

A class for handling clash detection operations within a USD stage.

This class provides methods for initializing and managing clash detection pipelines, setting configurations, processing overlaps, and handling clash data. It interfaces with the underlying clash detection API to perform these operations effectively.

Class Constants:

DEFAULT_SETTINGS: Dict[SettingId, Any]#

Default settings for the clash detection engine. All existing settings have default values set here.

Methods:

__init__()#

Initializes the ClashDetection class.

Creates a new clash detection context and initializes telemetry tracking.

destroy() → None#

Releases resources held by the clash detection context and API.

This method cleans up the clash detection API and context, freeing any allocated resources. After calling this method, the instance will no longer be usable for clash detection operations.

reset() → None#

Resets the clash detection context to its initial state.

This method clears any existing clash detection results and settings, returning the context to its default state while maintaining the API connection. Use this to start fresh without destroying the instance.

classmethod get_default_setting_value(setting_id: SettingId) → Any#

Returns the default (recommended default) value for a setting. If the setting is not found, returns None.

Parameters:

setting_id (SettingId) – The setting ID.

Returns:

The default value for the setting. Returns None if the setting is not found.

Return type:

Any

set_settings(
settings: Dict[str, Any],
stage: Usd.Stage | None = None,
) → bool#

Sets the settings for the clash detection.

Settings which are not provided in the dictionary are left unchanged.

Parameters:

  • settings (Dict[str, Any]) – The clash detection settings.

  • stage (Optional[Usd.Stage]) – The USD stage. Defaults to None.

Returns:

True if settings were applied successfully, False otherwise.

Return type:

bool

classmethod get_list_of_prims_int_paths(
stage: Usd.Stage,
prim_str_path: str,
add_prim_children: bool = False,
prim_accept_fn: Callable[[Usd.Prim], bool] | None = None,
) → Tuple[List[Sdf.Path], List[int]]#

Gets a list of prims in both Sdf.Path and integer path form.

Note

The returned Sdf.Path objects must be kept alive while using the integer paths, as the integer paths are derived from them.

Parameters:

  • stage (Usd.Stage) – The USD stage.

  • prim_str_path (str) – The path to the prim or collection. Can contain multiple paths separated by spaces.

  • add_prim_children (bool) – If True, includes paths of all child prims that match prim_accept_fn. Defaults to False.

  • prim_accept_fn (Optional[Callable[[Usd.Prim], bool]]) – Optional predicate function that takes a Usd.Prim and returns True if the prim should be included. Defaults to None.

Returns:

A tuple containing list of Sdf.Path objects and list of integer path representations.

Return type:

Tuple[List[Sdf.Path], List[int]]

set_scope(
stage: Usd.Stage,
obj_a: str,
obj_b: str,
merge_scopes: bool = False,
) → bool#

Sets the scope for clash detection.

  • If both obj_a and obj_b are empty -> process full scene.

  • If only the obj_a list contains items -> limit processing only to obj_a items.

  • If obj_a and obj_b lists contain items -> process obj_a against obj_b.

obj_a and obj_b can both contain multiple paths separated by spaces.

Parameters:

  • stage (Usd.Stage) – The USD stage.

  • obj_a (str) – Object A. Can contain multiple paths separated by space/tab/newline.

  • obj_b (str) – Object B. Can contain multiple paths separated by space/tab/newline.

  • merge_scopes (bool) – if True, then scopes are merged into one. Makes sense for detection of duplicates.

Returns:

True if scope was set successfully, False otherwise.

Return type:

bool

create_pipeline() → int#

Creates and initializes the clash detection pipeline.

This method sets up the pipeline for clash detection processing, records the start time, and captures initial memory state. The pipeline must be created before running any steps.

Returns:

The number of pipeline steps that need to be executed. Returns 0 if the clash detection API is not initialized.

Return type:

int

get_pipeline_step_data(index: int) → Any#

Gets metadata about a specific pipeline step.

Retrieves information about a pipeline step including its progress percentage and description. Can be called before or after executing the step.

Parameters:

index (int) – The index of the pipeline step to get data for.

Returns:

A data object containing progress (float 0.0-1.0) and name (str). Returns None if API not initialized.

Return type:

Any

run_pipeline_step(index: int) → None#

Executes a single step in the clash detection pipeline.

This method processes one step of the clash detection algorithm. The pipeline must be created first by calling create_pipeline(). Steps must be executed sequentially starting from index 0.

Parameters:

index (int) – Zero-based index of the pipeline step to execute.

get_async_pipeline_step_data(cookie: Any) → Any#

Gets data for the current step in an asynchronous clash detection pipeline.

Parameters:

cookie (Any) – Cookie obtained from run_async_pipeline() that identifies the pipeline instance.

Returns:

A data object containing progress (float) and name (str). Returns None if API not initialized.

Return type:

Any

run_async_pipeline() → Any#

Starts asynchronous execution of the clash detection pipeline.

Launches the clash detection process to run asynchronously in the background. The pipeline will execute all steps in separate threads without blocking the main thread.

Returns:

A cookie identifying this async pipeline instance. Returns None if API not initialized.

Return type:

Any

is_async_pipeline_running(cookie: Any) → bool#

Checks if an asynchronous clash detection pipeline is still executing.

Parameters:

cookie (Any) – Cookie obtained from run_async_pipeline().

Returns:

True if pipeline is still running, False if completed or API not initialized.

Return type:

bool

finish_async_pipeline(cookie: Any) → bool#

Cleans up resources used by an asynchronous clash detection pipeline.

This is a blocking call that waits for the pipeline to finish before cleaning up resources.

Parameters:

cookie (Any) – Cookie identifying the async pipeline instance to finish.

Returns:

True if cleanup was successful, False otherwise.

Return type:

bool

cancel_async_pipeline(cookie: Any) → None#

Cancels an asynchronous clash detection pipeline.

Signals the pipeline to stop processing but does not clean up resources. finish_async_pipeline() must still be called after cancellation.

Parameters:

cookie (Any) – Cookie identifying the pipeline instance to cancel.

compute_max_local_depth(
mesh_path0: Sdf.Path,
matrix0: Gf.Matrix4d,
mesh_path1: Sdf.Path,
matrix1: Gf.Matrix4d,
clash_query: ClashQuery,
) → float#

Computes the maximum local penetration depth between two meshes with given transforms.

Parameters:

  • mesh_path0 (Sdf.Path) – USD path to the first mesh.

  • matrix0 (Gf.Matrix4d) – Transformation matrix for the first mesh.

  • mesh_path1 (Sdf.Path) – USD path to the second mesh.

  • matrix1 (Gf.Matrix4d) – Transformation matrix for the second mesh.

  • clash_query (ClashQuery) – ClashQuery object containing clash detection settings.

Returns:

The maximum local penetration depth. Returns 0.0 if API not initialized.

Return type:

float

compute_penetration_depth(
mesh_path0: Sdf.Path,
matrix0: Gf.Matrix4d,
mesh_path1: Sdf.Path,
matrix1: Gf.Matrix4d,
clash_query: ClashQuery,
dir: Tuple[float, float, float],
) → Any#

Compute the penetration depth (amount and direction) necessary to resolve overlap between two meshes.

Parameters:

  • mesh_path0 (Sdf.Path) – USD path of the first mesh.

  • matrix0 (Gf.Matrix4d) – Local-to-world transformation for the first mesh.

  • mesh_path1 (Sdf.Path) – USD path of the second mesh.

  • matrix1 (Gf.Matrix4d) – Local-to-world transformation for the second mesh.

  • clash_query (ClashQuery) – ClashQuery that provides the relevant clash detection settings.

  • dir (Tuple[float, float, float]) – The penetration depth direction vector (x, y, z).

Returns:

An object containing depth (float) and dir (Tuple[float, float, float]). Returns None if API not initialized.

Return type:

Any

get_overlap_data(overlap_index: int, frame_index: int) → OverlapData#

Gets detailed data about a specific overlap at a given frame.

Parameters:

  • overlap_index (int) – Index identifying the specific overlap to query.

  • frame_index (int) – Frame number at which to get the overlap data.

Returns:

Object containing detailed overlap information.

Return type:

OverlapData

get_overlap_report(
overlap_index: int,
frame_index: int,
mesh_index: MeshIndex,
flags: int,
) → Dict[str, Any]#

Generates a detailed report about a specific overlap’s geometry.

Parameters:

  • overlap_index (int) – Index identifying the specific overlap to analyze.

  • frame_index (int) – Frame number at which to analyze the overlap.

  • mesh_index (MeshIndex) – Which mesh in the overlap pair to analyze.

  • flags (int) – Bit flags controlling which data to include in the report.

Returns:

Report containing usd_faces (warp array) and collision_outline (warp array).

Return type:

Dict[str, Any]

get_overlap_report2(
overlap_index: int,
frame_index: int,
flags: int,
) → Dict[str, Any]#

Generates a detailed report about a specific overlap’s geometry for both meshes involved.

This method queries the clash detection API for detailed information about an overlap at a given time/frame, returning the face indices for both meshes of the overlap, as well as the outline of the collision region. The results are converted into warp arrays for further processing and analysis.

Parameters:

  • overlap_index (int) – Index identifying the specific overlap to analyze.

  • frame_index (int) – Frame number at which to analyze the overlap.

  • flags (int) – Bit flags controlling which data to include in the report (see OverlapReportFlag).

Returns:

Report containing: - ‘usd_faces0’: Warp array of face indices for the first mesh in the overlap. - ‘usd_faces1’: Warp array of face indices for the second mesh in the overlap. - ‘collision_outline’: Warp array of outline vertices for the collision region. Returns an empty dict if the clash detection API is not initialized.

Return type:

Dict[str, Any]

Note

The difference between get_overlap_report() and get_overlap_report2() is that get_overlap_report() only returns face indices for a single mesh (specified by mesh_index) and the collision outline, whereas get_overlap_report2() returns face indices for both meshes (usd_faces0, usd_faces1) as well as the collision outline, and does not require a mesh index argument.

process_overlap_generator(
idx: int,
existing_overlaps: Dict[str, ClashInfo],
query_identifier: int,
setting_tolerance: float,
setting_depth_epsilon: float,
yield_progress_range: Tuple[float, float] = (0.0, 1.0),
) → Generator[float, None, ClashInfo]#

Processes a detected overlap, updating or creating a ClashInfo object as necessary.

Returns a generator that yields progress and finally returns ClashInfo.

Parameters:

  • idx (int) – The index of the overlap to process.

  • existing_overlaps (Dict[str, ClashInfo]) – Dictionary of existing clash info objects, keyed by clash hash.

  • query_identifier (int) – Unique identifier for the clash detection query.

  • setting_tolerance (float) – Distance tolerance value for determining soft clashes.

  • setting_depth_epsilon (float) – Minimum collision depth to consider for clash detection.

  • yield_progress_range (Tuple[float, float]) – Range of progress values to yield, as (min, max). Defaults to (0.0, 1.0).

Returns:

Generator yielding progress values, returns ClashInfo when complete.

Return type:

Generator[float, None, ClashInfo]

process_overlap(
stage: Usd.Stage,
idx: int,
existing_overlaps: Dict[str, ClashInfo],
query_identifier: int,
setting_tolerance: float,
setting_depth_epsilon: float,
) → ClashInfo#

Processes a detected overlap, updating or creating a ClashInfo object as necessary.

Parameters:

  • stage (Usd.Stage) – The USD stage containing the overlapping prims.

  • idx (int) – The index of the overlap to process.

  • existing_overlaps (Dict[str, ClashInfo]) – Dictionary of existing clash info objects.

  • query_identifier (int) – Unique identifier for the clash detection query.

  • setting_tolerance (float) – Distance tolerance value for determining soft clashes.

  • setting_depth_epsilon (float) – Minimum collision depth to consider.

Returns:

A ClashInfo object representing the processed overlap.

Return type:

ClashInfo

process_duplicate(
stage: Usd.Stage,
idx: int,
existing_overlaps: Dict[str, ClashInfo],
query_identifier: int,
) → ClashInfo#

Processes a detected duplicate overlap.

Duplicate overlap is an overlap between identical meshes with identical transformations fully overlapping each other.

Parameters:

  • stage (Usd.Stage) – The USD stage containing the overlapping meshes.

  • idx (int) – Index of the duplicate overlap to process.

  • existing_overlaps (Dict[str, ClashInfo]) – Dictionary of existing clash info objects.

  • query_identifier (int) – Unique identifier for the current clash detection query.

Returns:

Updated or newly created clash info object.

Return type:

ClashInfo

fetch_and_save_overlaps(
stage: Usd.Stage,
clash_data: ClashData,
clash_query: ClashQuery,
) → Iterator[float]#

Fetches and saves overlaps from clash detection, yielding progress updates.

Parameters:

  • stage (Usd.Stage) – The USD stage containing the meshes to check for clashes.

  • clash_data (ClashData) – Container for storing and managing clash information.

  • clash_query (ClashQuery) – Query parameters and settings for clash detection.

Returns:

A generator yielding progress values between 0.0 and 1.0. Returns -1 on error.

Return type:

Iterator[float]

Properties:

clash_detect_api: Any#

Gets the low-level clash detection API interface.

clash_detect_context: Any#

Gets the clash detection context handle.

is_out_of_memory: bool#

Checks if the clash detection engine encountered memory exhaustion.

get_nb_overlaps() → int#

Gets the total number of geometric overlaps detected.

Returns:

The total number of overlaps found, or 0 if no clashes detected or API not initialized.

Return type:

int

get_nb_duplicates() → int#

Gets the number of duplicate meshes detected.

Returns:

The number of duplicate meshes found, or 0 if none detected or API not initialized.

Return type:

int

Example#

Basic clash detection workflow:

from omni.physxclashdetectioncore.clash_detect import ClashDetection
from omni.physxclashdetectioncore.clash_detect_settings import SettingId
from pxr import Usd

# Initialize clash detection
clash_detect = ClashDetection()

# Configure settings
settings = {
    SettingId.SETTING_TOLERANCE.name: 0.0,  # Hard clashes
    SettingId.SETTING_DYNAMIC.name: False,   # Static detection
    SettingId.SETTING_LOGGING.name: True     # Enable logging
}

# Open stage
stage = Usd.Stage.Open("/path/to/stage.usd")

# Apply settings
clash_detect.set_settings(settings, stage)

# Set scope (full scene)
clash_detect.set_scope(stage, "", "")

# Run pipeline
num_steps = clash_detect.create_pipeline()
for i in range(num_steps):
    clash_detect.run_pipeline_step(i)

# Get results
num_overlaps = clash_detect.get_nb_overlaps()
print(f"Found {num_overlaps} overlaps")