Is this page helpful?

clash_info#

This module provides data structures for storing clash detection information.

Enumerations#

OverlapType#

class omni.physxclashdetectioncore.clash_info.OverlapType#

An enumeration representing the various overlap types.

Values:

NORMAL#: Normal overlap between meshes (same as MESH_MESH).

MESH_MESH#: Alias for NORMAL. Normal mesh vs mesh overlap.

DUPLICATE#: Completely overlapping with another identical mesh with identical transformation matrix.

POINT_CLOUD_MESH#: Point cloud vs mesh clash.

ClashState#

class omni.physxclashdetectioncore.clash_info.ClashState#

An enumeration representing the various states a clash can be in.

Values:

NEW#: Newly detected clash.

APPROVED#: Clash has been approved/acknowledged.

RESOLVED#: Clash has been resolved.

CLOSED#: Clash has been closed.

INVALID#: Clash is marked as invalid.

ACTIVE#: Clash is currently active.

Classes#

ClashFrameInfo#

class omni.physxclashdetectioncore.clash_info.ClashFrameInfo( timecode: float = 0.0, min_distance: float = 0.0, max_local_depth: float = -1.0, overlap_elements: int = 0, usd_faces_0: wp.array | None = None, usd_faces_1: wp.array | None = None, collision_outline: wp.array | None = None, object_0_matrix: Gf.Matrix4d | None = None, object_1_matrix: Gf.Matrix4d | None = None, device: str = 'cpu', usd_points_0: wp.array | None = None, usd_points_0_sizes: wp.array | None = None, )#

A class for storing information about a specific frame in a clash detection sequence.

This class contains details about a particular frame, including the timecode, minimum distance between objects, maximum local depth of a contact, number of overlapping triangles or points (for point cloud clashes), the faces or points involved in the clash, collision outline, and world matrices of both objects.

Parameters:

timecode (float) – The timecode in seconds of the frame at which the clash occurs. Defaults to 0.0.
min_distance (float) – The minimum distance between clashing objects. 0=Hard clash, otherwise soft clash. Defaults to 0.0.
max_local_depth (float) – The maximum depth of the local space of the clashing objects. -1 means no depth check. Defaults to -1.0.
overlap_elements (int) – The number of overlapping triangles (mesh-mesh) or points (point cloud clash) at this frame. Defaults to 0.
usd_faces_0 (Optional[wp.array]) – The face indices from the first object involved in the clash. Must have dtype=wp.uint32. Defaults to None.
usd_faces_1 (Optional[wp.array]) – The face indices from the second object involved in the clash. Must have dtype=wp.uint32. Defaults to None.
collision_outline (Optional[wp.array]) – Sequence of 3D points forming the collision outline. Must have dtype=wp.float32. Defaults to None.
object_0_matrix (Optional[Gf.Matrix4d]) – World transformation matrix of the first object at this frame. Defaults to None.
object_1_matrix (Optional[Gf.Matrix4d]) – World transformation matrix of the second object at this frame. Defaults to None.
device (str) – Target device for warp arrays. Can be “cpu” or “cuda:0” etc. Defaults to “cpu”.
usd_points_0 (Optional[wp.array]) – The point indices from the point cloud involved in the clash. Must have dtype=wp.uint32. Defaults to None.
usd_points_0_sizes (Optional[wp.array]) – The sizes of the points from the point cloud involved in the clash. If only one value is provided, it is used for all points. Must have dtype=wp.float32. Defaults to None.

Class Constants:

VERSION: int = 7#: Version of the ClashFrameInfo data structure.

EPSILON: float = 1e-6#: Epsilon value for floating point comparisons.

Methods:

serialize_to_dict() → Dict[str, Any]#

Converts the ClashFrameInfo instance to a dictionary in JSON-serializable format.

Returns:: Dictionary containing the serialized ClashFrameInfo data.
Return type:: Dict[str, Any]

classmethod deserialize_from_dict(data: Dict[str, Any]) → ClashFrameInfo | None#

Deserializes a ClashFrameInfo instance from a JSON-serializable dictionary format.

Parameters:: data (Dict[str, Any]) – Dictionary containing serialized ClashFrameInfo data.
Returns:: New ClashFrameInfo instance if deserialization succeeds, None if it fails.
Return type:: ClashFrameInfo | None

check_object_0_matrix_changed(mtx: Gf.Matrix4d) → bool#

Determines whether the matrix of the first object is different from the provided matrix.

Parameters:: mtx (Gf.Matrix4d) – The matrix to compare against the object’s stored matrix.
Returns:: Returns True if the object’s matrix differs; otherwise, False.
Return type:: bool

check_object_1_matrix_changed(mtx: Gf.Matrix4d) → bool#

Determines whether the matrix of the second object is different from the provided matrix.

Parameters:: mtx (Gf.Matrix4d) – The matrix to compare against the object’s stored matrix.
Returns:: Returns True if the object’s matrix differs; otherwise, False.
Return type:: bool

Properties:

timecode: float#: Read-only property that returns the timecode (time in seconds) of the frame where the clash was detected.

min_distance: float#: Gets the minimal distance between clashing objects.

max_local_depth: float#: Gets or sets the maximum local depth between clashing objects.

penetration_depth_px: float#: Gets or sets the penetration depth in the +X direction (1.0, 0.0, 0.0).

penetration_depth_nx: float#: Gets or sets the penetration depth in the -X direction (-1.0, 0.0, 0.0).

penetration_depth_py: float#: Gets or sets the penetration depth in the +Y direction (0.0, 1.0, 0.0).

penetration_depth_ny: float#: Gets or sets the penetration depth in the -Y direction (0.0, -1.0, 0.0).

penetration_depth_pz: float#: Gets or sets the penetration depth in the +Z direction (0.0, 0.0, 1.0).

penetration_depth_nz: float#: Gets or sets the penetration depth in the -Z direction (0.0, 0.0, -1.0).

overlap_elements: int#: Read-only property that returns the number of overlapping triangles (mesh-mesh clash) or points (point cloud clash) at this frame.

overlap_tris: int#: Read-only backward-compatibility shim. Returns overlap_elements when usd_points_0 is empty (i.e. this is a mesh-mesh clash frame), otherwise returns 0.

overlap_points: int#: Read-only backward-compatibility shim. Returns overlap_elements when usd_points_0 is non-empty (i.e. this is a point cloud clash frame), otherwise returns 0.

usd_faces_0: wp.array#: Read-only property that returns the indices of the faces from the first object involved in the clash.

usd_faces_1: wp.array#: Read-only property that returns the indices of the faces from the second object involved in the clash.

usd_points_0: wp.array#: Read-only property that returns the point indices from the point cloud involved in the clash (dtype=wp.uint32). Only populated for point cloud clashes (overlap_type == OverlapType.POINT_CLOUD_MESH).

usd_points_0_sizes: wp.array#: Read-only property that returns the sizes of the points from the point cloud involved in the clash (dtype=wp.float32). Only populated for point cloud clashes.

collision_outline: wp.array#: Read-only property that returns the collision outline (dtype=wp.float32) as a flat list of floats representing consecutive pairs of 3D points, where each pair defines one segment of the outline.

object_0_matrix: Gf.Matrix4d | None#: Gets the world transformation matrix of the first object at the timecode of the clash.

object_1_matrix: Gf.Matrix4d | None#: Gets the world transformation matrix of the second object at the timecode of the clash.

ClashInfo#

class omni.physxclashdetectioncore.clash_info.ClashInfo( identifier: int = -1, query_id: int = 0, overlap_id: str = '', overlap_type: OverlapType = OverlapType.NORMAL, present: bool = True, min_distance: float = 0.0, max_local_depth: float = 0.0, depth_epsilon: float = -1.0, tolerance: float = 0.0, object_a_path: str = '', object_a_mesh_crc: str = '', object_b_path: str = '', object_b_mesh_crc: str = '', start_time: float = 0.0, end_time: float = 0.0, num_records: int = 0, overlap_elements: int = 0, state: ClashState = ClashState.NEW, priority: int = 0, person_in_charge: str = '', creation_timestamp: datetime | None = None, last_modified_timestamp: datetime | None = None, last_modified_by: str = '', comment: str = '', clash_frame_info_items: Sequence[ClashFrameInfo] | None = None, )#

A class for managing and storing information about object clashes.

This class encapsulates details about object clashes such as their identifiers, overlap information, object paths, matrices, timestamps, and other metadata relevant to clash detection and management.

Parameters:

identifier (int) – Unique identifier for the clash. -1 means not yet assigned. Defaults to -1.
query_id (int) – Identifier for the originating clash set query. Defaults to 0.
overlap_id (str) – 128-bit hash representing the overlap, stored as a hex string. Defaults to “”.
overlap_type (OverlapType) – Type of the overlap. Defaults to OverlapType.NORMAL.
present (bool) – Indicates if the clash was present in the stage during the last run. Defaults to True.
min_distance (float) – Minimal distance between clashing objects. 0 means a hard clash; positive means a soft clash. Defaults to 0.0.
max_local_depth (float) – Maximum depth of the local space of the clashing objects. -1 means no depth check. Defaults to 0.0.
depth_epsilon (float) – Epsilon used to classify hard clashes vs contact cases. Negative value disables contact classification. Defaults to -1.0.
tolerance (float) – Overlapping tolerance. 0.0 means hard clashes; positive value enables soft (clearance) clashes up to that distance. Defaults to 0.0.
object_a_path (str) – Prim path to search set A (USD collection paths are also supported). Defaults to “”.
object_a_mesh_crc (str) – 128-bit mesh checksum for object A, used to detect mesh modifications. Defaults to “”.
object_b_path (str) – Prim path to search set B (USD collection paths are also supported). Defaults to “”.
object_b_mesh_crc (str) – 128-bit mesh checksum for object B, used to detect mesh modifications. Defaults to “”.
start_time (float) – For static clashes: timecode of the clash. For dynamic clashes: timecode of the first clash frame. Defaults to 0.0.
end_time (float) – For static clashes: same as start_time. For dynamic clashes: timecode of the last clash frame. Defaults to 0.0.
num_records (int) – For static clashes: always 1. For dynamic clashes: total number of clashing frames. Defaults to 0.
overlap_elements (int) – Number of overlapping triangles or points (point cloud clash). For dynamic clashes this is the maximum across all frames. Defaults to 0.
state (ClashState) – Current state of the clash. Defaults to ClashState.NEW.
priority (int) – Priority level of the clash for management purposes. Defaults to 0.
person_in_charge (str) – System-wide unique username of the person responsible for this clash. Defaults to “”.
creation_timestamp (Optional[datetime]) – Timestamp when the clash was first detected. Defaults to the current datetime.
last_modified_timestamp (Optional[datetime]) – Timestamp of the last user modification. Defaults to the current datetime.
last_modified_by (str) – OS username of the person who made the last modification. Defaults to the current OS username.
comment (str) – User-defined comment or note for the clash. Defaults to “”.
clash_frame_info_items (Optional[Sequence[ClashFrameInfo]]) – Per-frame clash detail records. None means not yet loaded from the database. Defaults to None.

Class Constants:

VERSION: int = 18#: Version of the ClashInfo data structure.

EPSILON: float = 1e-6#: Epsilon value for floating point comparisons.

Methods:

serialize_to_dict() → Dict[str, Any]#

Converts the ClashInfo instance to a dictionary in JSON-serializable format.

Returns:: Dictionary containing the serialized ClashInfo data.
Return type:: Dict[str, Any]

classmethod deserialize_from_dict( data: Dict[str, Any], reset_identifier: bool = False, ) → ClashInfo | None#

Deserializes a ClashInfo instance from a JSON-serializable dictionary format.

Parameters:

data (Dict[str, Any]) – Dictionary containing serialized ClashInfo data.
reset_identifier (bool) – If True, resets the identifier to -1 after deserialization. Defaults to False.

Returns:

New ClashInfo instance populated with the deserialized data. Returns None if deserialization fails.

Return type:

ClashInfo | None

get_frame_info_index_by_timecode(timecode: float) → int#

Finds the index of the frame info closest to the given timecode. Returns 0 if clash_frame_info_items is None or empty (e.g. frame data has not yet been loaded).

Parameters:: timecode (float) – The target timecode to search for.
Returns:: Index of the closest frame info, or 0 if frame data is unavailable.
Return type:: int

check_object_a_matrix_changed( stage: Usd.Stage, frame_info_index: int = 0, ) → bool#

Checks whether the matrix of object A at a given frame in the specified stage is different from the stored matrix.

Parameters:

stage (Usd.Stage) – The stage containing the object.
frame_info_index (int) – ClashFrameInfo index. Defaults to 0.

Returns:

Returns True if the object’s matrix differs; otherwise, False.

Return type:

bool

check_object_b_matrix_changed( stage: Usd.Stage, frame_info_index: int = 0, ) → bool#

Checks whether the matrix of object B at a given frame in the specified stage is different from the stored matrix.

Parameters:

stage (Usd.Stage) – The stage containing the object.
frame_info_index (int) – ClashFrameInfo index. Defaults to 0.

Returns:

Returns True if the object’s matrix differs; otherwise, False.

Return type:

bool

update_last_modified_timestamp() → None#: Updates both the last modified timestamp to the current datetime and the last_modified_by field to the current OS username.

get_clash_frame_info(index) → ClashFrameInfo | None#

Retrieves the clash frame info at the specified index.

When num_records is 1 and clash_frame_info_items is an empty sequence (frames not yet loaded from the database), a synthetic ClashFrameInfo is returned that is constructed from the top-level start_time, min_distance, max_local_depth, and overlap_elements fields. Returns None if clash_frame_info_items is None or the index is out of range.

Parameters:: index (int) – The index of the clash frame info to retrieve.
Returns:: The clash frame info at the specified index, a synthetic frame for single-record unloaded clashes, or None if not found.
Return type:: ClashFrameInfo | None

get_last_clash_frame_info() → ClashFrameInfo | None#

Retrieves the last clash frame info.

Returns:: The last clash frame info or None if not found.
Return type:: ClashFrameInfo | None

reset_identifier() → None#: Resets the identifier to -1 (unassigned). Used after deserialization when a fresh identity is needed.

Properties:

identifier: int#: Gets the unique identifier of the clash. -1 means not yet assigned.

query_id: int#: Gets the originating clash set query ID.

overlap_id: str#: Gets the overlap ID of the clash (128-bit hash as hex string).

overlap_type: OverlapType#: Gets the overlapping type of the clash.

is_contact: bool#: Gets whether the clash is a contact case. A clash is a contact when overlap_type is NORMAL, min_distance is 0.0, and max_local_depth is at or below depth_epsilon (or exactly 0.0 when depth_epsilon is non-positive).

is_hard_clash: bool#: Gets whether the clash is a hard clash. A clash is a hard clash when overlap_type is NORMAL, min_distance is 0.0, and it is not classified as a contact (see is_contact).

is_soft_clash: bool#: Gets whether the clash is a soft clash (clearance violation). A clash is a soft clash when overlap_type is NORMAL, min_distance is greater than 0.0, and it is not a contact.

is_duplicate: bool#: Gets whether the clash is a duplicate (fully overlapping identical meshes).

is_point_cloud_clash: bool#: Gets whether the clash is between a point cloud and a mesh (overlap_type == OverlapType.POINT_CLOUD_MESH).

present: bool#: Gets the presence status of the clash in the stage during the last run.

min_distance: float#: Gets the minimal distance between clashing objects.

max_local_depth: float#: Gets or sets the maximum local depth between clashing objects.

depth_epsilon: float#: Gets the depth epsilon of the clash. Used to classify hard clashes vs contact cases: clashes whose max_local_depth is at or below this value are treated as contacts. Use a negative value to disable contact classification (all zero-distance clashes become hard clashes).

penetration_depth_px: float#: Gets or sets the penetration depth in the +X direction.

penetration_depth_nx: float#: Gets or sets the penetration depth in the -X direction.

penetration_depth_py: float#: Gets or sets the penetration depth in the +Y direction.

penetration_depth_ny: float#: Gets or sets the penetration depth in the -Y direction.

penetration_depth_pz: float#: Gets or sets the penetration depth in the +Z direction.

penetration_depth_nz: float#: Gets or sets the penetration depth in the -Z direction.

tolerance: float#: Gets the overlapping tolerance of the clash. A value of 0.0 means hard clashes only; any positive value means soft (clearance) clashes up to that distance are also reported.

object_a_path: str#: Gets the path to object A.

object_a_mesh_crc: str#: Gets CRC checksum representing the mesh of the first object at the time of the clash.

object_b_path: str#: Gets the path to object B.

object_b_mesh_crc: str#: Gets CRC checksum representing the mesh of the second object at the time of the clash.

start_time: float#: Gets the start time of the clash. For static clashes this is the timecode of the clash itself; for dynamic clashes this is the timecode of the first detected clash frame.

end_time: float#: Gets the end time of the clash. For static clashes this equals start_time; for dynamic clashes this is the timecode of the last detected clash frame.

num_records: int#: Gets the number of clashing frames. For static clashes this is always 1; for dynamic clashes this is the number of frames in which the clash was detected.

overlap_elements: int#: Gets the number of overlapping triangles (mesh-mesh) or points (point cloud clash). For static clashes this is the count at the detected frame; for dynamic clashes it is the maximum count across all detected frames.

overlap_tris: int#: Backward-compatibility shim. Returns overlap_elements when is_point_cloud_clash is False (i.e. this is a mesh-mesh or duplicate clash), otherwise returns 0.

overlap_points: int#: Backward-compatibility shim. Returns overlap_elements when is_point_cloud_clash is True, otherwise returns 0.

state: ClashState#: Gets or sets the state of the clash.

priority: int#: Gets or sets the priority of the clash.

person_in_charge: str#: Gets or sets the name of the person responsible for addressing this clash.

creation_timestamp: datetime#: Gets the timestamp when the clash was first detected and recorded.

last_modified_timestamp: datetime#: Gets or sets the timestamp of the last modification made to this clash record.

last_modified_by: str#: Gets the name of the user who last modified this clash record.

comment: str#: Gets or sets a comment or note associated with the clash.

clash_frame_info_items: Sequence[ClashFrameInfo] | None#: Gets or sets the clash frame info items representing detailed information about each frame. None indicates that frame-level data has not yet been loaded (e.g. from the database). An empty sequence means the data was loaded but no per-frame records are present.