Clash Information

Overview

File Name: clash_info.py

The file 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: Optional[Sequence[int]] = None, usd_faces_1: Optional[Sequence[int]] = None, collision_outline: Optional[Sequence[float]] = None) → None

Initializes a new instance of the ClashFrameInfo class.

Parameters

timecode (float) – The timecode of the frame at which the clash occurs.
overlap_tris (int) – The number of overlapping triangles at this frame.
usd_faces_0 (Optional[Sequence[int]]) – The faces from the first object involved in the clash.
usd_faces_1 (Optional[Sequence[int]]) – The faces from the second object involved in the clash.
collision_outline (Optional[Sequence[float]]) – A flat list of floats representing a sequence of 3D points forming the collision outline.

Properties

timecode → float

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

Returns: The timecode value.
Return type: float

overlap_tris → int

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

Returns: The number of overlapping triangles.
Return type: int

usd_faces_0 → Sequence[int]

Read-only property that returns the indices of the faces from the first object involved in the clash.

Returns: The sequence of USD face indices for the first object.
Return type: Sequence[int]

usd_faces_1 → Sequence[int]

Read-only property that returns the indices of the faces from the second object involved in the clash.

Returns: The sequence of USD face indices for the second object.
Return type: Sequence[int]

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.

Returns: The sequence of collision outline points.
Return type: Sequence[float]

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 = 9: 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: Optional[Gf.Matrix4d] = None, object_a_matrix_changed: bool = False, object_b_path: str = '', object_b_mesh_crc: str = '', object_b_matrix: Optional[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: Optional[datetime] = None, last_modified_timestamp: Optional[datetime] = None, last_modified_by: str = '', comment: str = '', clash_frame_info_items: Optional[Sequence[ClashFrameInfo]] = None) → None

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

Parameters

identifier (int) – A database unique identifier for the clash instance.
query_id (int) – Identifies the originating clash set query that resulted in this clash, linking the clash to its detection query.
overlap_id (str) – A 128-bit hash used to uniquely identify the overlap between the two objects involved in the clash.
present (bool) – 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 (float) – 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 (str) – The prim path to a searchset A (USD collection is also supported), identifying the first object involved in the clash.
object_a_mesh_crc (str) – 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 (Optional[Gf.Matrix4d]) – The world matrix of object A.
object_a_matrix_changed (bool) – Indicates if object A’s matrix has changed since the last clash detection run. Not serialized.
object_b_path (str) – The prim path to a searchset B (USD collection is also supported), identifying the first object involved in the clash.
object_b_mesh_crc (str) – 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 (Optional[Gf.Matrix4d]) – The world matrix of object B.
object_b_matrix_changed (bool) – Indicates if object B’s matrix has changed since the last clash detection run. Not serialized.
start_time (float) – For static clashes, this is the timecode of the clash. For dynamic clashes, it’s the timecode of the first clash.
end_time (float) – For static clashes, this repeats the timecode of the clash. For dynamic clashes, it’s the timecode of the last clash.
num_records (int) – For static clashes, always 1; for dynamic clashes, the number of clashing ‘frames’.
overlap_tris (int) – For static clashes, the number of overlapping tris; for dynamic clashes, the max number of overlapping tris.
state (ClashState) – The current state of the clash, which can be new, validated, invalid, etc., represented by the ClashState enumeration.
priority (int) – The priority of the clash for management purposes, allowing clashes to be triaged or sorted based on urgency or importance.
person_in_charge (str) – A person identifier (usually a system-wide unique username) for the person responsible for addressing the clash.
creation_timestamp (Optional[datetime]) – 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 (Optional[datetime]) – 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 (str) – 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.
comment (str) – Any user-defined comment about the clash, allowing for additional notes or information to be stored.
clash_frame_info_items (Optional[Sequence[ClashFrameInfo]]) – 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 frame info closest to the given 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. Only static clashes or first record of dynamic clashes are supported at this point.

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 | None

Retrieves the last clash frame info item.

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

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: Gets the presence status of the clash in the stage during the last run.

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: Optional[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. Only static clashes or first record of dynamic clashes are supported at this point.

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: Optional[Gf.Matrix4d]: The world 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. Only static clashes or first record of dynamic clashes are supported at this point.

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.