Clash Information

Overview

The file clash_info.py defines classes for managing clash detection information between pairs of objects. It provides classes for providing comprehensive clash information together with detailed per-frame information for each clash.

OverlapType Enum

class OverlapType

An enumeration representing the type of overlap in a clash detection context. It distinguishes between hard and soft overlaps.

HARD: int = auto(): Represents a hard overlap (exact overlap).

SOFT: int = auto(): Represents a soft overlap (allowing for some clearance).

ClashState Enum

class ClashState

An enumeration representing the state of a clash within a project management or clash detection system. It defines the lifecycle of a clash from its discovery to its resolution.

NEW: int = auto(): Indicates that the clash has been newly discovered and has not yet been addressed. This is the initial state of a clash after it is detected.

APPROVED: int = auto(): Represents the state where the clash has been reviewed and approved for further investigation or action. This state is typically assigned after an initial review process.

RESOLVED: int = auto(): Denotes that the clash has been addressed, and a solution has been implemented. The clash is considered resolved but remains in the system for record-keeping and verification.

CLOSED: int = auto(): Indicates that the clash has been fully resolved and all necessary actions have been completed. The clash is closed and no further action is required.

INVALID: int = auto(): Signifies that the clash was determined to be a false positive or otherwise not a genuine issue. The clash is marked as invalid and typically removed from active consideration.

ClashFrameInfo Class

class ClashFrameInfo: A class that encapsulates information about a frame in a clash detection context.

Constants

VERSION: int = 2: The version number of the ClashFrameInfo class for serialization purposes.

Constructor

__init__(timecode: float = 0.0, overlap_tris: int = 0, usd_faces_0: Sequence[int] = None, usd_faces_1: Sequence[int] = None, collision_outline: Sequence[float] = None)

Initializes a new instance of the ClashFrameInfo class.

Parameters

timecode (float) – The timecode of the frame.
overlap_tris (int) – The number of overlapping triangles.
usd_faces_0 (Sequence[int]) – A sequence of integers representing USD faces for the first object.
usd_faces_1 (Sequence[int]) – A sequence of integers representing USD faces for the second object.
collision_outline (Sequence[float]) – A sequence of floats representing a sequence of couples of 3D points, each forming a segment. This is a flat list of floats representing the collision outline.

Properties

timecode: float: Read-only property that returns the timecode of the frame where the clash was detected.

overlap_tris: int: Read-only property that returns the number of overlapping triangles detected in this frame.

usd_faces_0: Sequence[int]: Read-only property that returns the indices of the faces from the first object involved in the clash.

usd_faces_1: Sequence[int]: Read-only property that returns the indices of the faces from the second object involved in the clash.

collision_outline: Sequence[float]: Read-only property that returns a flat list of floats representing a sequence of 3D points forming the collision outline. Each couple of points forms a segment.

ClashInfo Class

class ClashInfo: A class that encapsulates detailed information about a detected clash. It includes metadata about the clash, such as identifiers, paths to the involved objects, detailed per-frame information for each clash, and the state of the clash.

Constants

VERSION: int = 8: The version number of the ClashInfo class for serialization purposes.

EPSILON: float = 1e-6: A small value used for numerical comparisons to account for floating-point precision issues. Used when determining if matrix of an object has changed.

Constructor

__init__(identifier: int = 0, query_id: int = 0, overlap_id: str = '', present: bool = True, tolerance: float = 0.0, object_a_path: str = '', object_a_mesh_crc: str = '', object_a_matrix: Gf.Matrix4d = None, object_a_matrix_changed: bool = False, object_b_path: str = '', object_b_mesh_crc: str = '', object_b_matrix: Gf.Matrix4d = None, object_b_matrix_changed: bool = False, start_time: float = 0.0, end_time: float = 0.0, num_records: int = 0, overlap_tris: int = 0, state: ClashState = ClashState.NEW, priority: int = 0, person_in_charge: str = '', creation_timestamp: datetime = None, last_modified_timestamp: datetime = None, last_modified_by: str = '', snapshot=None, comment: str = '', clash_frame_info_items: Optional[Sequence[ClashFrameInfo]] = None)

Initializes a new instance of the ClashInfo class with specified parameters.

Parameters

identifier – A database unique identifier for the clash instance.
query_id – Identifies the originating clash set query that resulted in this clash, linking the clash to its detection query.
overlap_id – A 128-bit hash used to uniquely identify the overlap between the two objects involved in the clash.
present – Indicates whether the clash was present in the stage during the last run. A boolean value where True means the clash was present, and False means it was not.
tolerance – Specifies the overlapping tolerance. A value of 0.0 means only hard clashes (exact overlaps) are considered, while any value above 0.0 indicates soft clashes (allowing for some clearance).
object_a_path – The prim path to a searchset A (USD collection is also supported), identifying the first object involved in the clash.
object_a_mesh_crc – A 128-bit mesh checksum for object A, allowing the system to detect if the mesh has been modified since the last clash detection run.
object_a_matrix – The world matrix of object A.
object_a_matrix_changed – Indicates if object A’s matrix has changed since the last clash detection run.
object_b_path – The prim path to a searchset B (USD collection is also supported), identifying the first object involved in the clash.
object_b_mesh_crc – A 128-bit mesh checksum for object B, allowing the system to detect if the mesh has been modified since the last clash detection run.
object_b_matrix – The world matrix of object B.
object_b_matrix_changed – Indicates if object B’s matrix has changed since the last clash detection run.
start_time – For static clashes, this is the timecode of the clash. For dynamic clashes, it’s the timecode of the first clash.
end_time – For static clashes, this repeats the timecode of the clash. For dynamic clashes, it’s the timecode of the last clash.
num_records – For static clashes, always 1; for dynamic clashes, the number of clashing ‘frames’.
overlap_tris – For static clashes, the number of overlapping tris; for dynamic clashes, the max number of overlapping tris.
state – The current state of the clash, which can be new, validated, invalid, etc., represented by the ClashState enumeration.
priority – The priority of the clash for management purposes, allowing clashes to be triaged or sorted based on urgency or importance.
person_in_charge – A person identifier (usually a system-wide unique username) for the person responsible for addressing the clash.
creation_timestamp – The timestamp when the clash was first found, providing a record of when the clash was initially detected. Default is the current date and time if None is provided.
last_modified_timestamp – The last user modification timestamp, indicating the most recent time the clash information was updated. Default is the current date and time if None is provided.
last_modified_by – The system username of the person who made the last modification to the clash information. Default is the current user’s name if an empty string is provided.
snapshot – Reserved for future use, intended to hold a snapshot ID or multiple IDs related to the clash.
comment – Any user-defined comment about the clash, allowing for additional notes or information to be stored.
clash_frame_info_items – Information for each clashing frame. None indicates that it was not loaded, while a sequence of ClashFrameInfo objects provides detailed frame-by-frame clash data.

Methods

get_frame_info_index_by_timecode(timecode: float) → int

Finds the index of the closest clash frame info item by timecode.

Parameters: timecode (float) – The timecode to search for.
Returns: The index of the closest clash frame info item.
Return type: int

check_matrix_changed(stage: Usd.Stage) → bool

Checks if the matrix of either object A or B has changed.

Parameters: stage (Usd.Stage) – The USD stage to check matrices on.
Returns: True if either matrix has changed, False otherwise.
Return type: bool

update_last_modified_timestamp() → None: Updates the last modified timestamp to the current datetime.

get_clash_frame_info(index) → ClashFrameInfo | None

Retrieves the clash frame info item at the specified index.

Parameters: index (int) – The index of the clash frame info item to retrieve.
Returns: The clash frame info item at the specified index, or None if not found.
Return type: ClashFrameInfo | None

get_last_clash_frame_info() → ClashFrameInfo

Retrieves the last clash frame info item.

Returns: The last clash frame info item.
Return type: ClashFrameInfo

Properties

identifier: int: A unique identifier for the clash instance.

query_id: int: The identifier of the query that detected this clash.

overlap_id: str: A unique string identifier for the overlap causing the clash.

present: bool: Indicates whether the clash is currently present in the scene.

tolerance: float: The tolerance value used in detecting this clash.

object_a_path: str: The USD path of the first object involved in the clash.

object_a_mesh_crc: str: A CRC checksum representing the mesh of the first object at the time of the clash.

object_a_matrix: Gf.Matrix4d: The transformation matrix of the first object at the time of the clash.

object_a_matrix_changed: bool: Indicates whether the transformation matrix of the first object has changed since the clash was detected.

object_b_path: str: The USD path of the second object involved in the clash.

object_b_mesh_crc: str: A CRC checksum representing the mesh of the second object at the time of the clash.

object_b_matrix: Gf.Matrix4d: The transformation matrix of the second object at the time of the clash.

object_b_matrix_changed: bool: Indicates whether the transformation matrix of the second object has changed since the clash was detected.

start_time: float: The start time of the clash in the scene’s timeline.

end_time: float: The end time of the clash in the scene’s timeline.

num_records: int: The number of records or instances where this clash was detected.

overlap_tris: int: The number of overlapping triangles that constitute the clash.

state: ClashState: The current state of the clash, represented by a ClashState enum.

priority: int: The priority level of the clash, used for sorting or categorization.

person_in_charge: str: The name of the person responsible for addressing this clash.

creation_timestamp: datetime: The timestamp when the clash was first detected and recorded.

last_modified_timestamp: datetime: The timestamp of the last modification made to this clash record.

last_modified_by: str: The name of the user who last modified this clash record.

snapshot: Any: Reserved for future use, intended to hold a snapshot ID or multiple IDs related to the clash.

comment: str: A comment or note associated with the clash, typically used for additional information or resolution steps.

clash_frame_info_items: Optional[Sequence[ClashFrameInfo]]: A sequence of ClashFrameInfo objects representing detailed information about each frame in which the clash was detected.