Python USD ModelLink (pumolink)

Python USD ModelLink is an Omniverse Extension that offers a library to easily develop kit applications. This library allows you to connect Python classes and OpenUSD Prims using decorators. Corresponding instances of the Python class are created as soon as a corresponding prim is added to the stage. The instance is also removed when the prim is deleted. Attributes can be easily observed. You can easily register for various events. Dependency Injection is also used to be able to use all common Omniverse/OpenUsd objects.

Installation and how to get?

• Use Omniverse Extension Manager

Usage

The connection of Python classes and OpenUSD Prims are called link.

Import from modellink

Import what you need, read the API Documentation for all possibilities.

from modellink import linked, on_update, usd_attr

Define the link

Define which UsdSchema should be connected to your Python class ('Cube', in this case). Links can also be created without UsdSchema, see API documentation.

@linked('Cube')
class MyDevice:
    ...

Injection

If necessary, just have a few Omniverse or OpenUsd objects injected, e.g. the Stage.

Python USD ModelLink uses a library called 'Injector' for dependency injection. For more information see: https://pypi.org/project/injector/

    @inject
    def __init__(self, stage: Usd.Stage ) -> None:
        ...

Events

Event decorators starting with 'on_' and in this example the 'update' event is used. So the name for the decorator is: 'on_update'.

    @on_update
    def update(self, prim: Usd.Prim):
        self.rot += 0.5
        setRotate(prim, Gf.Vec3f(0.0, self.rot, 0.0))

Observe Prim attributes

You can also simply observe Usd Prim attributes.

    @usd_attr('size')
    def attr_size_change(self, val: float):
        carb.log_info(f"attr_change .size={val}")

Full example

from injector import inject
from modellink import linked, on_update, usd_attr


@linked('Cube')
class MyDevice:

    @inject
    def __init__(self, stage: Usd.Stage ) -> None:
        carb.log_info("init called!")
        self._stage = stage
        self.rot = 0.0

    @on_update
    def update(self, prim: Usd.Prim):
        self.rot += 0.5
        setRotate(prim, Gf.Vec3f(0.0, self.rot, 0.0))

    @usd_attr('size')
    def attr_size_change(self, val: float):
        carb.log_info(f"attr_change .size={val}")

Most Important Decorators

Note

Do not use these decorators together with @inject. All decorators inject just like @inject

Decorator	Description	Parameters
@linked	Linked a class to a Prim. The correct prim is recognized using 'detection'. The detection can be specified as an argument to the decorator. This decorator is for classes only.	@linked or @linked() will activate any prim that contains the entry linkedClass='yourClass' in customData or assetInfo. @linked('YourSchema') will activate any Prim where the Schema is 'YourPrim' @linked(your_function) will activate any Prim where a function def your_function(prim: Usd.Prim)->bool returns True
@usd_attr	Observes a Prim attribute. The function is called every time the attribute changes. The changed value is passed to the method as argument with the name of the attribute or the name specified in param_name. This decorator is for member functions only.	@usd_attr('attributeName')
@on_update	The function is called by an 'update' event. This decorator is for member functions only.	@on_update (only if 'playing') or @on_update(editmode=True) (always)
@on_play	The function is called by a 'play' event. This decorator is for member functions only.
@on_pause	The function is called by a 'pause' event. This decorator is for member functions only.
@on_stop	The function is called by a 'stop' event. This decorator is for member functions only.
@on_event	The function is called by any self named event. This decorator is for member functions only.	@on_event('my_custom_event_name')

Contribution

We welcome contributions to our open-source GitHub project! Whether it's adding features, fixing bugs, or improving documentation, your help is appreciated. Check out our repository and join our community of contributors. Thank you for your support! (Contributing, Code of conduct)