SnapProvider

class omni.kit.manipulator.tool.snap.SnapProvider(viewport_api)

Bases: ABC

An abstract base class for snap providers in a manipulator tool.

This class defines the interface for snap operations in manipulators. Implementors should provide functionality for snapping objects in 3D space based on the given parameters.

Parameters: viewport_api – The API for interacting with the viewport in which snapping occurs.

Methods

`__init__`(viewport_api)	Initializes the SnapProvider with the given viewport API.
`can_enable_menu`(object)	Returns if the provider can be enabled on the menu.
`can_orient`()	Returns if the provider may change the orientation of the object during a snap.
`can_show_menu`(object)	Returns if the provider can appear in the menu list of all providers.
`destroy`()	Cleans up any resources or state held by the provider.
`get_display_name`()	Returns the display name of the provider.
`get_name`()	Returns the name/id of the provider.
`get_order`()	Returns the priority order of the snap provider.
`on_began`(excluded_paths, **kwargs)	Initializes the snap operation with a list of paths to exclude from snapping.
`on_ended`(**kwargs)	Resets the state of the provider when the snap operation ends.
`on_snap`(xform, ndc_location, scene_view, ...)	Called when manipulator wants to perform a snap operation.
`require_viewport_api`()	Returns if the provider requires viewport_api to work.

__init__(viewport_api)

Initializes the SnapProvider with the given viewport API.

Parameters: viewport_api – The API for interacting with the viewport in which snapping occurs.

static can_enable_menu(object: dict) → bool

Returns if the provider can be enabled on the menu.

Parameters: object – A dictionary containing context information about the object.
Returns: True if the provider can be enabled, False otherwise.
Return type: bool

abstract static can_orient() → bool

Returns if the provider may change the orientation of the object during a snap.

Returns: True if the snap provider can change orientation, False otherwise.
Return type: bool

classmethod can_show_menu(object: dict) → bool

Returns if the provider can appear in the menu list of all providers.

Parameters: object – A dictionary containing context information about the object.
Returns: True if the provider can be shown in the menu, False otherwise.
Return type: bool

destroy(): Cleans up any resources or state held by the provider.

classmethod get_display_name() → str

Returns the display name of the provider. It will be used on the menu. If not overridden, it falls back to get_name() instead.

Returns: The display name of the snap provider.
Return type: str

abstract static get_name() → str

Returns the name/id of the provider. This is the internal name used for the snap manager.

Returns: The name/id of the snap provider.
Return type: str

static get_order() → float

Returns the priority order of the snap provider. If more than one provider is enabled at the same time and both are able to provide snap results, the one with the lower order wins.

Returns: The priority order of the provider.
Return type: float

on_began(excluded_paths: List[Union[str, Path]], **kwargs)

Initializes the snap operation with a list of paths to exclude from snapping.

Parameters: excluded_paths – A list of paths that should be excluded from snapping calculations.

on_ended(**kwargs): Resets the state of the provider when the snap operation ends.

abstract on_snap(xform: Matrix4d, ndc_location: Sequence[float], scene_view: SceneView, want_orient: bool, want_keep_spacing: bool, on_snapped: Callable, conform_up_axis: str, enabled_providers: List[SnapProvider], *args, **kwargs) → bool

Called when manipulator wants to perform a snap operation. Only the current selected snap provider will be called.

Parameters

xform – Transformation of the current manipulator object.
ndc_location – Location of the cursor in NDC space.
scene_view – SceneView of the manipulator that triggers this snap request.
want_orient – If the snap provider can change the orientation of the object to be snapped (e.g., conform to normal), it should supply ‘orient’ to ‘on_snapped’ when ‘want_orient’ is True.
want_keep_spacing – When multiple objects are selected, indicates if the original spacing between them should be maintained.
on_snapped – A callback function receiving ‘**kwargs’. Depending on if the snap is successful and settings, ‘position’, ‘path’, ‘orient’ may be provided to it.
conform_up_axis – The up axis to be used to conform to the target orientation.
enabled_providers – All enabled providers for hint purposes. Do NOT modify the content.

Returns

True if the snap is successful. If the snap is an asynchronous operation, return True if the request of snapping is successful.: False if the snap failed or cannot be requested.

Return type

bool

static require_viewport_api() → bool

Returns if the provider requires viewport_api to work.

Returns: True if viewport_api is required, False otherwise.
Return type: bool