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.

NORMAL: int = auto()#

Represents a normal overlap (hard or soft).

DUPLICATE: int = auto()#

Represents a duplicate; Completely overlapping with another identical mesh with identical transformation matrix.

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 = 4

The version number of the ClashFrameInfo class for serialization purposes.

Constructor#

__init__(
self,
timecode: float = 0.0,
min_distance: float = 0.0,
overlap_tris: int = 0,
usd_faces_0: Sequence[int] | None = None,
usd_faces_1: Sequence[int] | None = None,
collision_outline: Sequence[float] | None = None,
object_0_matrix: Gf.Matrix4d | None = None,
object_1_matrix: Gf.Matrix4d | None = None,
) → None#

Initializes a new instance of the ClashFrameInfo class.

Parameters:

  • timecode (float, default=0.0) – The timecode in seconds of the frame at which the clash occurs.

  • min_distance (float, default=0.0) – The minimum distance between clashing objects.

  • overlap_tris (int, default=0) – The number of overlapping triangles at this frame.

  • usd_faces_0 (Optional[Sequence[int]], default=None) – The faces from the first object involved in the clash.

  • usd_faces_1 (Optional[Sequence[int]], default=None) – The faces from the second object involved in the clash.

  • collision_outline (Optional[Sequence[float]], default=None) – A flat list of floats representing a sequence of 3D points forming the collision outline.

  • object_0_matrix (Optional[Gf.Matrix4d], default=None) – World matrix of the first object involved in the clash.

  • object_1_matrix (Optional[Gf.Matrix4d], default=None) – World matrix of the second object involved in the clash.

Methods#

def check_object_0_matrix_changed(self, 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

def check_object_1_matrix_changed(self, 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 contains the timecode of the frame where the clash was detected.

min_distance: float

Read-only property that contains the minimal distance between clashing objects.

overlap_tris: int

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

usd_faces_0: Sequence[int]

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

usd_faces_1: Sequence[int]

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

collision_outline: Sequence[float]

Read-only property that contains a flat list of floats representing a sequence of 3D points forming the collision outline. Each couple of points forms a segment.

object_0_matrix(self): Gf.Matrix4d | None#

Read-only property that contains world transformation matrix of the first object at the timecode of the clash.

object_1_matrix(self): Gf.Matrix4d | None#

Read-only property that contains world transformation matrix of the second object at the timecode of the clash.

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 = 12#

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__(
self,
identifier: int = 0,
query_id: int = 0,
overlap_id: str = '',
overlap_type: OverlapType = OverlapType.NORMAL,
present: bool = True,
min_distance: float = 0.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_tris: 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,
) → 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.

  • overlap_type (OverlapType) – Type of the overlap.

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

  • min_distance (float) – Minimal distance between clashing objects. 0=Hard clash, otherwise soft clash.

  • 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_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.

  • 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_object_a_matrix_changed(
self,
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.

Returns:

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

Return type:

bool

check_object_b_matrix_changed(
self,
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.

Returns:

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

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.

overlap_type: OverlapType#

The overlapping type of the clash.

is_hard_clash: bool#

Whether the clash is a hard clash.

is_soft_clash: bool#

Whether the clash is a soft clash.

is_duplicate: bool#

Whether the clash is a duplicate (fully overlapping identical meshes with identical transformation matrices).

present: bool#

The presence status of the clash in the stage during the last run.

min_distance: float#

The minimal distance between clashing objects.

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

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.

comment: str#

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

clash_frame_info_items: Sequence[ClashFrameInfo] | None#

A sequence of ClashFrameInfo objects representing detailed information about each frame in which the clash was detected.

On this page