Clash Detection Engine Encapsulation#

Overview#

File Name: clash_detect.py

This file provides a ClashDetection class that encapsulates the core functionality for clash detection operations within a USD stage. The 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 (by leveraging the omni.physx.clashdetection extension) to perform these operations effectively.

ClashDetection Class#

class 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.

Constructor#

__init__() → None

Initializes a new instance of the ClashDetection class, setting up the clash detection API and context.

Methods#

destroy() → None

Releases the clash detection API and context. Should be called to clean up resources when the clash detection is no longer needed.

reset() → None

Resets the clash detection context to its initial state.

get_nb_overlaps() → int#

Gets the number of overlaps detected in the current context.

Returns:

The number of detected overlaps (clashes).

Return type:

int

get_nb_duplicates() → int#

Gets the number of duplicates (identical meshes with identical transformations fully overlapping each other) detected.

Returns:

The number of duplicates.

Return type:

int

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

Sets the settings for the clash detection.

Note

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

Parameters:

  • settings – The clash detection settings.

  • stage – The USD stage.

Returns:

True if settings were applied successfully, False otherwise.

Return type:

bool

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,
) → List[int]#

This class method gets a list of prims in ‘int path’ form.

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. If False, only returns the path of the specified prim. 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. Only used when add_prim_children is True. If None, all active and visible prims are accepted. Defaults to None.

Returns:

List of prim paths converted to integer form. For a prim input, returns either just the prim path or paths of all matching child prims based on add_prim_children. For a collection input, returns paths of all prims in the collection (add_prim_children is ignored).

Return type:

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 between 0.0 and 1.0) and name (str) description of the pipeline step. Returns None if clash detection API is 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. Progress and step information can be obtained by calling get_pipeline_step_data().

The step execution is synchronous and will block until completed. For asynchronous execution, use run_async_pipeline() instead.

Parameters:

index (int) – Zero-based index of the pipeline step to execute. Must be less than the number of steps returned by create_pipeline().

run_async_pipeline() → Any#

Runs the clash detection pipeline asynchronously.

Returns:

A cookie identifying the async pipeline instance. Returns None if clash detection API is not initialized.

Return type:

Any

is_async_pipeline_running(cookie: Any) → bool#

Checks if an asynchronous pipeline is still running.

Parameters:

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

Returns:

True if the pipeline is still running, False otherwise.

Return type:

bool

get_async_pipeline_step_data(cookie: Any) → Any#

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

This method retrieves information about the current step being processed by the async pipeline, including progress percentage and step name. It can be called repeatedly while is_async_pipeline_running() returns True to monitor pipeline execution.

Parameters:

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

Returns:

Data about the current pipeline step.

Return type:

Any

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. The cookie becomes invalid after this call and cannot be reused. Results like get_nb_overlaps() can only be accessed after this function returns.

Parameters:

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

Returns:

True if cleanup was successful, False if clash detection API is not initialized or cleanup failed.

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 to properly clean up the pipeline.

Parameters:

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

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. Returns an empty OverlapData object if the clash detection API is not initialized.

Return type:

OverlapData

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

Generates a report for a specific overlap, frame, and mesh index.

Parameters:

  • overlap_index (int) – The overlap index.

  • frame_index (int) – The frame index.

  • mesh_index (MeshIndex) – The mesh index.

  • flags (OverlapReportFlag) – Flags for the overlap report.

Returns:

The overlap report.

Return type:

Dict[str, Any]

get_overlap_faces(
overlap_index: int,
frame_index: int,
mesh_index: int,
) → List[int]#

Gets the overlap faces for a specific overlap, frame, and mesh.

Parameters:

  • overlap_index (int) – The overlap index.

  • frame_index (int) – The frame index.

  • mesh_index (int) – The mesh index.

Returns:

The overlap faces.

Return type:

List[int]

get_overlap_outline(
overlap_index: int,
frame_index: int,
) → List[float]#

Gets the overlap outline for a specific overlap and frame. It is a flat array of floats grouped in sets of three, representing x, y, and z coordinates.

Parameters:

  • overlap_index (int) – The overlap index.

  • frame_index (int) – The frame index.

Returns:

The overlap outline.

Return type:

List[float]

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 meshes.

  • idx (int) – 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 current clash detection query.

  • setting_tolerance (float) – Tolerance value for clash detection.

  • setting_depth_epsilon (float) – Depth epsilon value for clash detection.

Returns:

Updated or newly created clash info object.

Return type:

ClashInfo

process_overlap_generator(
stage: Usd.Stage,
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 (identifier -1 means new clash info otherwise it’s an update).

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, 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:

A generator yielding progress values and finally returning a ClashInfo object.

Return type:

Generator[float, None, ClashInfo]

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

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

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, keyed by clash hash.

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

Returns:

Updated or newly created clash info object containing the duplicate overlap data.

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.

This method processes both normal overlaps and duplicate meshes (if enabled), updating the clash data with new clash information. Progress is reported via an iterator.

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.

Return type:

Iterator[float]

get_pipeline_telemetry() → Dict[str, Any]#

Gets telemetry data about the pipeline execution.

Returns:

Dictionary containing pipeline execution metrics like start time, memory usage, etc.

Return type:

Dict[str, Any]

Properties#

clash_detect_api -> Any

Returns the underlying clash detection API interface used by this instance.

Returns:

Clash detection engine API.

clash_detect_context -> Any

Provides access to the current clash detection context.

Returns:

Clash detection engine API context.

is_out_of_memory -> bool

Checks if the clash detection engine ran out of memory during its last run.

Returns:

True if it did run out of memory, False otherwise.

Return type:

bool