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 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, the faces involved in the clash, collision outline, and world matrices of both objects.

Constants#

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

EPSILON: float = 1e-6: A small value used for numerical comparisons to account for floating-point precision issues.

Constructor#

__init__( self, timecode: float = 0.0, min_distance: float = 0.0, max_local_depth: float = -1.0, overlap_tris: int = 0, usd_faces_0: wp.array(dtype=wp.uint32) | None = None, usd_faces_1: wp.array(dtype=wp.uint32) | None = None, collision_outline: wp.array(dtype=wp.float32) | None = None, object_0_matrix: Gf.Matrix4d | None = None, object_1_matrix: Gf.Matrix4d | None = None, device: str = 'cpu', ) → 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. 0=Hard clash, otherwise soft clash.
max_local_depth (float, default=-1.0) – The maximum depth of the local space of the clashing objects. -1 means no depth check.
overlap_tris (int, default=0) – The number of overlapping triangles at this frame.
usd_faces_0 (Optional[wp.array(dtype=wp.uint32)], default=None) – The faces from the first object involved in the clash.
usd_faces_1 (Optional[wp.array(dtype=wp.uint32)], default=None) – The faces from the second object involved in the clash.
collision_outline (Optional[wp.array(dtype=wp.float32)], default=None) – Sequence of 3D points forming the collision outline.
object_0_matrix (Optional[Gf.Matrix4d], default=None) – World transformation matrix of the first object at this frame.
object_1_matrix (Optional[Gf.Matrix4d], default=None) – World transformation matrix of the second object at this frame.
device (str, default="cpu") – Target device for warp arrays (“cpu” or “cuda:0” etc).

Methods#

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

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

serialize_to_dict(self) → 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]

deserialize_from_dict( cls, 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

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 the maximum local depth between clashing objects.

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

usd_faces_0: wp.array(dtype=wp.uint32): Read-only property that returns the indices of the faces from the first object involved in the clash.

usd_faces_1: wp.array(dtype=wp.uint32): Read-only property that returns the indices of the faces from the second object involved in the clash.

collision_outline: wp.array(dtype=wp.float32): Read-only property that returns the collision outline. This is a flat list of floats representing a sequence of couples of 3D points, each forming a segment.

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#

class ClashInfo#

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.

Constants#

VERSION: int = 15#: 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 = -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_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#

noindex:

Initializes a new instance of the ClashInfo class.

param identifier:

Unique identifier for the clash. -1 means not yet assigned / uninitialized.

type identifier:

int

param query_id:

Identifier for the originating clash set query.

type query_id:

int

param overlap_id:

128-bit hash representing the overlap.

type overlap_id:

str

param overlap_type:

Type of the overlap.

type overlap_type:

OverlapType

param present:

Indicates if the clash was present during the last run.

type present:

bool

param min_distance:

Minimal distance between clashing objects. 0=Hard clash, otherwise soft clash.

type min_distance:

float

param max_local_depth:

The maximum depth of the local space of the clashing objects. -1 means no depth check.

type max_local_depth:

float

param depth_epsilon:

The depth epsilon of the clash.

type depth_epsilon:

float

param tolerance:

Overlapping tolerance; 0.0 means hard clashes, any value above means soft clashes.

type tolerance:

float

param object_a_path:

Prim path to a search set A.

type object_a_path:

str

param object_a_mesh_crc:

128-bit mesh checksum for object A.

type object_a_mesh_crc:

str

param object_b_path:

Prim path to a search set B.

type object_b_path:

str

param object_b_mesh_crc:

128-bit mesh checksum for object B.

type object_b_mesh_crc:

str

param start_time:

Timecode of the first clash for dynamic clashes.

type start_time:

float

param end_time:

Timecode of the last clash for dynamic clashes.

type end_time:

float

param num_records:

Number of clashing frames for dynamic clashes.

type num_records:

int

param overlap_tris:

Number of overlapping triangles.

type overlap_tris:

int

param state:

Current state of the clash (e.g., NEW, APPROVED, RESOLVED).

type state:

ClashState

param priority:

Priority level of the clash for management purposes.

type priority:

int

param person_in_charge:

Identifier of the person responsible for the clash.

type person_in_charge:

str

param creation_timestamp:

Timestamp when the clash was first found.

type creation_timestamp:

Optional[datetime]

param last_modified_timestamp:

Timestamp of the last user modification.

type last_modified_timestamp:

Optional[datetime]

param last_modified_by:

Username of the person who made the last modification.

type last_modified_by:

str

param comment:

User-defined comment.

type comment:

str

param clash_frame_info_items:

Information for each clashing frame.

type clash_frame_info_items:

Optional[Sequence[ClashFrameInfo]]

Methods#

serialize_to_dict(self) → Dict[str, Any]

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

Returns:: Dictionary containing the serialized ClashInfo data, with all attributes converted to JSON-serializable format using the default obj_to_dict behavior.
Return type:: Dict[str, Any]

deserialize_from_dict( cls, 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.

Returns:

New ClashInfo instance populated with the deserialized data, or 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.

Parameters:: timecode (float) – The target timecode to search for.
Returns:: Index of the closest frame info.
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#: Unique identifier for the clash.

query_id: int#: Identifier for the originating clash set query.

overlap_id: str#: 128-bit hash representing the overlap.

overlap_type: OverlapType#: Type of the overlap.

is_contact: bool#: Whether the clash is a contact case.

is_hard_clash: bool#: Whether the clash is a hard clash.

is_soft_clash: bool#: Whether the clash is a soft clash.

present: bool#: Indicates if the clash was present during the last run.

min_distance: float#: Minimal distance between clashing objects. 0=Hard clash, otherwise soft clash.

max_local_depth: float#: The maximum depth of the local space of the clashing objects. -1 means no depth check.

depth_epsilon: float#: The depth epsilon of the clash.

tolerance: float#: Overlapping tolerance; 0.0 means hard clashes, any value above means soft clashes.

object_a_path: str#: Prim path to a search set A.

object_a_mesh_crc: str#: 128-bit mesh checksum for object A.

object_b_path: str#: Prim path to a search set B.

object_b_mesh_crc: str#: 128-bit mesh checksum for object B.

start_time: float#: Timecode of the first clash for dynamic clashes.

end_time: float#: Timecode of the last clash for dynamic clashes.

num_records: int#: Number of clashing frames for dynamic clashes.

overlap_tris: int#: Number of overlapping triangles.

state: ClashState#: Current state of the clash (e.g., NEW, APPROVED, RESOLVED).

priority: int#: Priority level of the clash for management purposes.

person_in_charge: str#: Identifier of the person responsible for the clash.

creation_timestamp: datetime#: Timestamp when the clash was first found.

last_modified_timestamp: datetime#: Timestamp of the last user modification.

last_modified_by: str#: Username of the person who made the last modification.

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.