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 the clash detection pipeline.

Returns:

The number of pipeline steps.

Return type:

int

get_pipeline_step_data(index: int) → Any#

Gets data for a specific pipeline step.

Parameters:

index (int) – The index of the pipeline step.

Returns:

Data for the specified pipeline step.

Return type:

Any

run_pipeline_step(index: int) → None#

Runs a specific step in the clash detection pipeline.

Parameters:

index (int) – The index of the pipeline step.

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

Gets overlap data for a specified overlap and frame index.

Parameters:

  • overlap_index (int) – The overlap index.

  • frame_index (int) – The frame index.

Returns:

Data for the specified overlap.

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,
) → Generator[float, None, None]#

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 a generator.

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 as floats between 0 and 1+ representing the percentage complete.

Return type:

Generator[float, None, None]

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

On this page