omni.kit.commands¶

Changelog

Commands and Undo/Redo system.

Command is undo/redo system primitive. It is a class which gets instantiated and do method is called on an instance. The instance is stored then in undo stack if it contains an undo method. When undo is called undo method will be executed on the same instance.

To create a command derive from omni.kit.commands.Command and add a do method and optionally undo method. If you consider also redo operation do()/undo() methods can be called inifinite amout of times. You can also create command with only do() method which would means it is not undoable and won’t be added to undo stack.

Here is a simple example:

import omni.kit.commands

class NumIncrement(omni.kit.commands.Command):
    def __init__(num: int):
        self._num = num

    def do(self):
        self._num = self._num + 1
        return self._num # Result can be optionally returned

    def undo(self):
        self._num = self._num - 1

Here we create a command class NumIncrement. By inhering from omni.kit.commands.Command it is automatically discovered and registered by Kit if it is inside one of public extensions module. You can also register it explicitly with: omni.kit.commands.register(NumIncrement) call. To execute a command one can call x = omni.kit.commands.execute("NumIncrement", num=10) from anywhere. Commands may also return values in do method.

Guidelines¶

There are some useful rules to follow when creating a command:

All arguments must be simple types (numbers, strings, lists etc) to enable serialization and calling of commands from a console.
Try to make commands as simple as possible. Compose complex commands of other commands using grouping to minimize side effects.
Write at least one test for each command!
To signal failure from a command, raise an Error. This will automatically trigger the command (and any descendants) to call undo if they define it.

Groups¶

Commands can be grouped meaning that executing a group of commands will execute all of them and undo and redo operations will also cover the whole group.

First of all commands executed inside of a command are grouped automatically:

import omni.kit.commands

class SpawnFewPrims(omni.kit.commands.Command):
    def do(self):
        omni.kit.commands.execute("CreatePrimWithDefaultXform", prim_type="Sphere")
        omni.kit.commands.execute("CreatePrimWithDefaultXform", prim_type="Cone")

    def undo(self):
        pass

In this example you don’t even need to write an undo method. Undoing that command will automatically call undo on nested commands. But you must define undo method to hint that command is undoable.

One can explicitly group commands using API:

import omni.kit.commands

omni.kit.undo.begin_group()
omni.kit.commands.execute("CreatePrimWithDefaultXform", prim_type="Sphere")
omni.kit.commands.execute("CreatePrimWithDefaultXform", prim_type="Cone")
omni.kit.undo.end_group()

# or similiarly:

with omni.kit.undo.group():
    omni.kit.commands.execute("CreatePrimWithDefaultXform", prim_type="Sphere")
    omni.kit.commands.execute("CreatePrimWithDefaultXform", prim_type="Cone")

C++ Support¶

Commands were originally written in (and only available to use from) Python, but they can now be registered, deregistered, executed, and undone/redone from C++

Commands registered from C++ should always be deregistered from C++ (although deregistering them from Python may not be fatal).
Commands registered from Python should always be deregistered from Python (although deregistering them from C++ may not be fatal).
All C++ commands have an ‘undo’ function on the Python side (unlike Python commands which can be created without undo functionality), so when executed they will always be placed on the undo/redo stack.

C++ Usage Examples

Command API Reference¶

omni.kit.undo.begin_disabled()¶: Begin preventing Commands being added to the undo stack. Must be paired with a subsequent call to end_disabled()

omni.kit.undo.begin_group()¶: Begin group of Commands.

omni.kit.undo.can_redo()¶

omni.kit.undo.can_repeat()¶

omni.kit.undo.can_undo()¶

omni.kit.undo.clear_history()¶: Clear Command execution history.

omni.kit.undo.clear_stack()¶

omni.kit.undo.disabled()¶

Prevent commands being added to the undo stack.

This function is a context manager.

Example:

with omni.kit.undo.disabled():
    omni.kit.commands.execute("Foo1")
    omni.kit.commands.execute("Foo2")

omni.kit.undo.end_disabled()¶: Stop preventing Commands being added to the undo stack. Must be paired with a prior call to begin_disabled()

omni.kit.undo.end_group()¶: End group of Commands.

omni.kit.undo.execute(command, name, kwargs) → Tuple[bool, Any]¶

omni.kit.undo.format_exception(e: Exception, remove_n_last_frames: int = 2) → str¶

Pretty format exception. Include exception info, call stack of exception itself and this function callstack. This function is meant to be used in except clause.

Parameters

e – Exception.
remove_n_last_frames – Number of last call stack frames to be removed. Usually this function and few above are meaningless to the user.

Returns

Formatted string.

omni.kit.undo.get_history()¶

Get Command execution history.

Returns a list of tuples: HistoryEntry(Command name, Arguments, Groupping level, Error status).

omni.kit.undo.get_redo_stack()¶

omni.kit.undo.get_undo_stack()¶

omni.kit.undo.group()¶

Group multiple commands in one.

This function is a context manager.

Example:

with omni.kit.undo.group():
    omni.kit.commands.execute("Foo1")
    omni.kit.commands.execute("Foo2")

omni.kit.undo.redo()¶

omni.kit.undo.register_undo_commands()¶

omni.kit.undo.repeat()¶

omni.kit.undo.subscribe_on_change(on_change)¶

omni.kit.undo.subscribe_on_change_detailed(on_change)¶

omni.kit.undo.undo()¶

omni.kit.undo.unsubscribe_on_change(on_change)¶

omni.kit.undo.unsubscribe_on_change_detailed(on_change)¶

Commands for Omniverse Kit.

omni.kit.commands module is used to register and execute Commands. It is built on top of omni.kit.undo module to enable undo/redo operations with Commands.

Command is any class with do() method and optionally undo() method. If Command has undo() method it is put on the undo stack when executed. It must be inherited from Command class for type checking.

Example of creating your command, registering it, passing arguments and undoing.

class MyOrange(omni.kit.commands.Command):
    def __init__(self, bar: list):
        self._bar = bar

    def do(self):
        self._bar.append('orange')

    def undo(self):
        del self._bar[-1]

>>> import omni.kit.commands
>>> omni.kit.commands.register(MyOrangeCommand)
>>> my_list = []
>>> omni.kit.commands.execute("MyOrange", bar=my_list)
>>> my_list
['orange']
>>> import omni.kit.undo
>>> omni.kit.undo.undo()
>>> my_list
[]
>>> omni.kit.undo.redo()
>>> my_list
['orange']

class omni.kit.commands.Command¶

Base class for all Commands.

abstract do()¶

modify_callback_info(cb_type: str, args: Dict[str, Any]) → Dict[str, Any]¶

Returns a dictionary of information to be passed to callbacks of the given type.

By default callbacks are passed a copy of the arguments which were passed to execute() when the command was invoked. This method can be overridden to modify that information for specific callback types.

Parameters

cb_type – Type of callback the information will be passed to.
args – A dictionary containing a copy of the arguments with which the command was invoked. This is a shallow copy so implementations may add, remove or replace dictionary elements but should not modify any of the objects contained within it.

Returns

A dictionary of information to be passed to callbacks of the specified type.

class omni.kit.commands.CommandBridge¶

on_shutdown()¶

on_startup()¶

class omni.kit.commands.CommandExt¶

Monitor for new extensions and register all commands in python modules of those extensions, along with setting up a bridge that allows commands to be registered and executed from C++, and registration of actions that wrap some basic command functionality like undo and redo.

on_shutdown()¶

on_startup(ext_id)¶

omni.kit.commands.create(name, **kwargs)¶

Create Command object.

Parameters

name – Command name.
**kwargs – Arbitrary keyword arguments to be passed into into Command constructor.

Returns

Command object if succeeded. None if failed.

omni.kit.commands.deregister_actions(extension_id)¶

omni.kit.commands.execute(name, **kwargs) → Tuple[bool, Any]¶

Execute Command.

Parameters

name – Command name. Can be class name (e.g. “My”) or full name including module (e.g. “foo.bar.MyCommand”)
**kwargs – Arbitrary keyword arguments to be passed into into Command constructor.

omni.kit.commands.execute_argv(name, argv: list) → Tuple[bool, Any]¶

Execute Command using argument list..

Attempts to convert argument list into Command’s kwargs. If a Command has get_argument_parser method defined, it will be called to get argparse.ArgumentParser instance to use for parsing. Otherwise command docstring is used to extract argument information.

Parameters

name – Command name.
argv – Argument list.

omni.kit.commands.get_argument_parser_from_function(function)¶

omni.kit.commands.get_command_class(name: str) → Type[omni.kit.commands.command.Command]¶

Get Command class(type) by name.

Parameters: name – Command name. It may include a module name to be more specific and avoid conflicts.
Returns: Command class if succeeded. None if can’t find a command with this name.

omni.kit.commands.get_command_class_signature(name: str)¶

Get the init signature for a Command.

Parameters: name – Command name. It may include a module name to be more specific and avoid conflicts.
Returns: __init__ signature

omni.kit.commands.get_command_doc(name: str) → str¶

Get Command docstring by name.

Parameters: name – Command name. It may include a module name to be more specific and avoid conflicts.
Returns: Python docstring (__doc__) from a command type.

omni.kit.commands.get_command_parameters(name: str) → List[Type[omni.kit.commands.command.CommandParameter]]¶

Get all parameters for a Commands.

Parameters: name – Command name. It may include a module name to be more specific and avoid conflicts.
Returns: A list of CommandParameter (except ‘self’ parameter)

omni.kit.commands.get_commands()¶: Get all registered Commands.

omni.kit.commands.get_commands_list() → List[Type[omni.kit.commands.command.Command]]¶: Return list of all Command classes registered.

omni.kit.commands.register(command_class: Type[omni.kit.commands.command.Command])¶

Register a Command.

Parameters: command_class – Command class.

omni.kit.commands.register_actions(extension_id)¶

omni.kit.commands.register_all_commands_in_module(module)¶

Register all Commands found in specified module.

Register all classes in module which inherit omni.kit.commands.Command.

Parameters

module – Module name or module object.

Returns

An accessor object that contains a function for every command to execute it. e.g. if you register the commands “Run” and “Hide” then the accessor behaves like:

class Accessor:
    @staticmethod
    def Run(**kwargs):
        execute("Run", **kwargs)
    @staticmethod
    def Hide(**kwargs):
        execute("Hide", **kwargs)

This gives you a nicer syntax for running your commands:

cmds = register_all_commands_in_module(module)
cmds.Run(3.14)
cmds.Hide("Behind the tree")

omni.kit.commands.register_callback(name: str, cb_type: str, callback: Callable[[Dict[str, Any]], None]) → omni.kit.commands.command.CallbackID¶

Register a callback for a command.

Parameters

name – Command name. It may include a module name to be more specific and avoid conflicts.
cb_type – Type of callback. Currently supported types are: PRE_DO_CALLBACK - called before the command is executed POST_DO_CALLBACK - called after the command is executed
callback – Callable to be called. Will be passed a dictionary of information specific to that command invocation. By default the dictionary will contain the parameters passed to execute(), but this may be overridden by individual commands so check their documentation. Many command parameters are optional so it is important that callbacks check for their presence before attempting to access them. The callback must not make any changes to the dictionary passed to it.

Returns

An ID that can be passed to unregister_callback.

omni.kit.commands.set_logging_enabled(enabled: bool)¶

omni.kit.commands.subscribe_on_change(on_change)¶: Subscribe to module change events. Triggered when commands added, executed.

omni.kit.commands.unregister(command_class: Type[omni.kit.commands.command.Command])¶

Unregister a Command.

Parameters: command_class – Command class.

omni.kit.commands.unregister_callback(id: omni.kit.commands.command.CallbackID)¶

Unregister a command callback previously registered through register_callback.

Parameters: id – The ID returned by register_callback when the callback was registered.

omni.kit.commands.unregister_module_commands(command_interface)¶

Unregister the list of commands registered by register_all_commands_in_module

Parameters: command_interface – An object whose only members are command classes that were registered

omni.kit.commands.unsubscribe_on_change(on_change)¶: Unsubscribe to module change events.