Overview
Use collision boxes to determine the placement footprint of an item before and after geometry is loaded. Collision boxes help applications position items accurately and detect placement conflicts during insertion, drag-and-drop, placement, and collision detection operations. The Content Platform provides both an initial collision box and a computed collision box to support these scenarios.
Collision box types
The Content Platform provides two collision box representations:
- Initial Collision Box
- Computed Collision Box
Each representation supports a different stage of item placement and geometry processing.
Initial collision box
The initial collision box is authored content returned by the
getItemVariant API. It is used during item insertion and drag-and-drop operations before the item geometry is loaded. Because it provides a lightweight footprint, the initial collision box enables applications to perform placement operations without requiring the complete item geometry.The user can define the values manually, or use the command ComputeItemCollisionBoxCommand to generate the collision box values automatically.
Computed collision box
The computed collision box is generated from the item's geometry and provides a more accurate placement footprint based on the assembled item. To ensure consistent behaviour across applications, the collision box returned by the
getItemVariant API should match the computed collision box for the item's default configuration. How the computed collision box is calculated
The computed collision box is generated using the following process:
- Resolve the item and all its sub-items.
- Exclude sub-items that match the configured exclusion rules.
- Calculate the minimum and maximum coordinates of all remaining geometry.
- Create a bounding box that encompasses the resulting geometry.
- Store the calculated collision box on the item.
The stored collision box can then be returned by platform APIs and consumed by applications for placement and collision detection
Excluded sub-items
The following sub-item classifications are excluded from the computed collision box calculation:
- plumbingFixture.sink
- spaceholder.plumbingFixture.sink
- spaceholder.appliance.cooktop
- appliance.cooktop
- cabinetry.front
- Assembly with subtype door
- Assembly with subtype drawer
These exclusions help ensure that the collision box represents the structural footprint of the item rather than components that should not participate in placement and collision scenarios.
Note: Excluded sub-items may still be visible in the final geometry. The list of excluded sub-items may change as new use cases are introduced.
Example
Consider a sink base cabinet containing the following components:
- Cabinet carcase
- Worktop
- Sink
- Doors
The computed collision box includes:
- Cabinet carcase
- Worktop
The computed collision box excludes:
- Sink
- Doors
As a result, the collision box represents the cabinet footprint used for placement and collision detection.
Visualise a Collision Box in the 3D Authoring Viewer
To visualise a collision box in the 3D Authoring Viewer, use the Toggle Collision Box
option from the Tools bar at the bottom of the viewer to display the collision box around the selected item. Once enabled, you can further configure its display in the Settings section under CollisionBox Settings.
The Variant CollisionBox option shows the collision box calculated by the platform for the geometry only (or according to the geometry settings), while GLTF CollisionBox displays the collision box calculated by the platform based on the assembled item and its subitems. These options help you inspect and debug how the platform calculates the physical boundaries of a product.
Important considerations
- The initial collision box is used before geometry is loaded.
- The computed collision box is generated from geometry and should be used as the primary placement footprint.
- The collision box is intended for placement and collision detection and does not necessarily represent the full graphical extent of an item.
- Excluded sub-items may still be visible in the final geometry.
- If an item's configuration changes and affects its geometry, the collision box should be recomputed to reflect the updated footprint.