grutopia.core.util

array

Sub-module containing utilities for working with different array backends.

grutopia.core.util.array.TENSOR_TYPES = {'numpy': <class 'numpy.ndarray'>, 'torch': <class 'torch.Tensor'>, 'warp': <class 'warp.types.array'>}

A dictionary containing the types for each backend.

The keys are the name of the backend (“numpy”, “torch”, “warp”) and the values are the corresponding type (np.ndarray, torch.Tensor, wp.array).

grutopia.core.util.array.TENSOR_TYPE_CONVERSIONS = {'numpy': {<class 'warp.types.array'>: <function <lambda>>, <class 'torch.Tensor'>: <function <lambda>>}, 'torch': {<class 'warp.types.array'>: <function <lambda>>, <class 'numpy.ndarray'>: <function <lambda>>}, 'warp': {<built-in function array>: <function <lambda>>, <class 'torch.Tensor'>: <function <lambda>>}}

A nested dictionary containing the conversion functions for each backend.

The keys of the outer dictionary are the name of target backend (“numpy”, “torch”, “warp”). The keys of the inner dictionary are the source backend (np.ndarray, torch.Tensor, wp.array).

grutopia.core.util.array.TensorData

Type definition for a tensor data.

Union of numpy, torch, and warp arrays.

alias of Union[ndarray, Tensor, array]

grutopia.core.util.array.convert_to_torch(array: ndarray | Tensor | array, dtype: dtype | None = None, device: device | str | None = None) → Tensor

Converts a given array into a torch tensor.

The function tries to convert the array to a torch tensor. If the array is a numpy/warp arrays, or python list/tuples, it is converted to a torch tensor. If the array is already a torch tensor, it is returned directly.

If device is None, then the function deduces the current device of the data. For numpy arrays, this defaults to “cpu”, for torch tensors it is “cpu” or “cuda”, and for warp arrays it is “cuda”.

Note

Since PyTorch does not support unsigned integer types, unsigned integer arrays are converted to signed integer arrays. This is done by casting the array to the corresponding signed integer type.

Parameters:

• array – The input array. It can be a numpy array, warp array, python list/tuple, or torch tensor.

• dtype – Target data-type for the tensor.

• device – The target device for the tensor. Defaults to None.

Returns:

The converted array as torch tensor.

assets

configclass

Sub-module that provides a wrapper around the Python 3.7 onwards dataclasses module.

grutopia.core.util.configclass.configclass(cls, **kwargs)

Wrapper around dataclass functionality to add extra checks and utilities.

As of Python 3.7, the standard dataclasses have two main issues which makes them non-generic for configuration use-cases. These include:

1. Requiring a type annotation for all its members.

2. Requiring explicit usage of field(default_factory=...)() to reinitialize mutable variables.

This function provides a decorator that wraps around Python’s dataclass utility to deal with the above two issues. It also provides additional helper functions for dictionary <-> class conversion and easily copying class instances.

Usage:

from dataclasses import MISSING

from omni.isaac.orbit.utils.configclass import configclass


@configclass
class ViewerCfg:
    eye: list = [7.5, 7.5, 7.5]  # field missing on purpose
    lookat: list = field(default_factory=[0.0, 0.0, 0.0])


@configclass
class EnvCfg:
    num_envs: int = MISSING
    episode_length: int = 2000
    viewer: ViewerCfg = ViewerCfg()

# create configuration instance
env_cfg = EnvCfg(num_envs=24)

# print information as a dictionary
print(env_cfg.to_dict())

# create a copy of the configuration
env_cfg_copy = env_cfg.copy()

# replace arbitrary fields using keyword arguments
env_cfg_copy = env_cfg_copy.replace(num_envs=32)

Parameters:

• cls – The class to wrap around.

• **kwargs – Additional arguments to pass to dataclass().

Returns:

The wrapped class.

dict

Sub-module for utilities for working with dictionaries.

grutopia.core.util.dict.class_to_dict(obj: object) → dict[str, Any]

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:

obj – An instance of a class to convert.

Raises:

ValueError – When input argument is not an object.

Returns:

Converted dictionary mapping.

grutopia.core.util.dict.convert_dict_to_backend(data: dict, backend: str = 'numpy', array_types: Iterable[str] = ('numpy', 'torch', 'warp')) → dict

Convert all arrays or tensors in a dictionary to a given backend.

This function iterates over the dictionary, converts all arrays or tensors with the given types to the desired backend, and stores them in a new dictionary. It also works with nested dictionaries.

Currently supported backends are “numpy”, “torch”, and “warp”.

Note

This function only converts arrays or tensors. Other types of data are left unchanged. Mutable types (e.g. lists) are referenced by the new dictionary, so they are not copied.

Parameters:

• data – An input dict containing array or tensor data as values.

• backend – The backend (“numpy”, “torch”, “warp”) to which arrays in this dict should be converted. Defaults to “numpy”.

• array_types – A list containing the types of arrays that should be converted to the desired backend. Defaults to (“numpy”, “torch”, “warp”).

Raises:

ValueError – If the specified backend or array_types are unknown, i.e. not in the list of supported backends (“numpy”, “torch”, “warp”).

Returns:

The updated dict with the data converted to the desired backend.

grutopia.core.util.dict.dict_to_md5_hash(data: object) → str

Convert a dictionary into a hashable key using MD5 hash.

Parameters:

data – Input dictionary or configuration object to convert.

Returns:

A string object of double length containing only hexadecimal digits.

grutopia.core.util.dict.print_dict(val, nesting: int = -4, start: bool = True)

Outputs a nested dictionary.

grutopia.core.util.dict.update_class_from_dict(obj, data: dict[str, Any], _ns: str = '') → None

Reads a dictionary and sets object variables recursively.

This function performs in-place update of the class member attributes.

Parameters:

• obj – An instance of a class to update.

• data – Input dictionary to update from.

• _ns – Namespace of the current object. This is useful for nested configuration classes or dictionaries. Defaults to “”.

Raises:

• TypeError – When input is not a dictionary.

• ValueError – When dictionary has a value that does not match default config type.

• KeyError – When dictionary has a key that does not exist in the default config type.

grutopia.core.util.dict.update_dict(orig_dict: dict, new_dict: Mapping) → dict

Updates existing dictionary with values from a new dictionary.

This function mimics the dict.update() function. However, it works for nested dictionaries as well.

Reference:

https://stackoverflow.com/questions/3232943/update-value-of-a-nested-dictionary-of-varying-depth

Parameters:

• orig_dict – The original dictionary to insert items to.

• new_dict – The new dictionary to insert items from.

Returns:

The updated dictionary.

math

omni_usd_util

grutopia.core.util.omni_usd_util.compute_path_bbox(prim_path: str) → Tuple[Double3, Double3]

Compute Bounding Box using omni.usd.UsdContext.compute_path_world_bounding_box See https://docs.omniverse.nvidia.com/kit/docs/omni.usd/latest/omni.usd/omni.usd.UsdContext.html# omni.usd.UsdContext.compute_path_world_bounding_box

Parameters:

prim_path – A prim path to compute the bounding box.

Returns:

A range (i.e. bounding box) as a minimum point and maximum point.

grutopia.core.util.omni_usd_util.get_grabbed_able_xform_paths(root_path: str, prim: Prim, depth: int = 3) → List[str]

get all prim paths of Xform objects under specified prim.

Parameters:

• root_path (str) – root path of scenes.

• prim (Usd.Prim) – target prim.

• depth (int, optional) – expected depth of Xform objects relative to root_path. Defaults to 3.

Returns:

prim paths.

Return type:

List[str]

grutopia.core.util.omni_usd_util.get_pick_position(robot_base_position: ndarray, prim_path: str) → ndarray

Get the pick position for a manipulator robots to pick an objects at prim_path. The pick position is simply the nearest top vertex of the objects’s bounding box.

Parameters:

• robot_base_position (np.ndarray) – robots base position.

• prim_path (str) – prim path of objects to pick.

Returns:

pick position.

Return type:

np.ndarray

grutopia.core.util.omni_usd_util.get_world_transform_xform(prim: Prim) → Tuple[Vec3d, Rotation, Vec3d]

Get the local transformation of a prim using omni.usd.get_world_transform_matrix(). See https://docs.omniverse.nvidia.com/kit/docs/omni.usd/latest/omni.usd/omni.usd.get_world_transform_matrix.html :param prim: The prim to calculate the world transformation.

Returns:

• Translation vector.

• Rotation quaternion, i.e. 3d vector plus angle.

• Scale vector.

Return type:

A tuple of

grutopia.core.util.omni_usd_util.nearest_xform_from_position(stage: Stage, xform_paths: List[str], position: ndarray, threshold: float = 0) → str

get prim path of nearest Xform objects from the target position.

Parameters:

• stage (Usd.Stage) – usd stage.

• xform_paths (List[str]) – full list of xforms paths.

• position (np.ndarray) – target position.

• threshold (float, optional) – max distance. Defaults to 0 (unlimited).

Returns:

prim path of the Xform objects, None if not found.

Return type:

str

python

A set of utility functions for general python usage

class grutopia.core.util.python.Recreatable

Simple class that provides an abstract interface automatically saving __init__ args of the classes inheriting it.

get_init_info()

Grabs relevant initialization information for this class instance. Useful for directly reloading an objects from this information, using @create_object_from_init_info.

Returns:

Nested dictionary that contains this objects’ initialization information

Return type:

dict

class grutopia.core.util.python.RecreatableAbcMeta(clsname, bases, clsdict)

A composite metaclass of both RecreatableMeta and ABCMeta.

Adding in ABCMeta to resolve metadata conflicts.

class grutopia.core.util.python.RecreatableMeta(clsname, bases, clsdict)

Simple metaclass that automatically saves __init__ args of the instances it creates.

class grutopia.core.util.python.Registerable

Simple class template that provides an abstract interface for registering classes.

class grutopia.core.util.python.Serializable

Simple class that provides an abstract interface to dump / load states, optionally with serialized functionality as well.

deserialize(state)

De-serializes flattened 1D numpy array @state into nested dictionary state. Should be implemented by subclass.

Parameters:

state (n-array) – encoded + serialized, 1D numerical np.array capturing this objects’s state

Returns:

Keyword-mapped states of these objects. Should match structure of output from

self._dump_state()

Return type:

dict

dump_state(serialized=False)

Dumps the state of this objects in either dictionary of flattened numerical form.

Parameters:

• serialized (bool) – If True, will return the state of this objects as a 1D numpy array. Otherwise,

• a (will return) –

Returns:

Either:

• Keyword-mapped states of these objects, or

• encoded + serialized, 1D numerical np.array capturing this objects’ state, where n is @self.state_size

Return type:

dict or n-array

load_state(state, serialized=False)

Deserializes and loads this objects’ state based on @state

Parameters:

• state (dict or n-array) –

  Either: - Keyword-mapped states of these objects, or - encoded + serialized, 1D numerical np.array capturing this objects’ state,

  where n is @self.state_size

• serialized (bool) – If True, will interpret @state as a 1D numpy array. Otherwise, will assume the input is a (potentially nested) dictionary of states for this objects

serialize(state)

Serializes nested dictionary state @state into a flattened 1D numpy array for encoding efficiency. Should be implemented by subclass.

Parameters:

state (dict) – Keyword-mapped states of this objects to encode. Should match structure of output from self._dump_state()

Returns:

encoded + serialized, 1D numerical np.array capturing this objects’s state

Return type:

n-array

property state_size

Returns: int: Size of this objects’s serialized state

class grutopia.core.util.python.SerializableNonInstance

Identical to Serializable, but intended for non-instance classes

classmethod deserialize(state)

De-serializes flattened 1D numpy array @state into nested dictionary state. Should be implemented by subclass.

Parameters:

state (n-array) – encoded + serialized, 1D numerical np.array capturing this objects’s state

Returns:

Keyword-mapped states of this objects. Should match structure of output from

self._dump_state()

Return type:

dict

classmethod dump_state(serialized=False)

Dumps the state of this objects in either dictionary of flattened numerical form.

Parameters:

• serialized (bool) – If True, will return the state of this objects as a 1D numpy array. Otherwise,

• a (will return) –

Returns:

Either:

• Keyword-mapped states of these objects, or

• encoded + serialized, 1D numerical np.array capturing this objects’ state, where n is @self.state_size

Return type:

dict or n-array

classmethod load_state(state, serialized=False)

Deserializes and loads this objects’ state based on @state

Parameters:

• state (dict or n-array) –

  Either: - Keyword-mapped states of these objects, or - encoded + serialized, 1D numerical np.array capturing this objects’ state,

  where n is @self.state_size

• serialized (bool) – If True, will interpret @state as a 1D numpy array. Otherwise, will assume the input is a (potentially nested) dictionary of states for this objects

classmethod serialize(state)

Serializes nested dictionary state @state into a flattened 1D numpy array for encoding efficiency. Should be implemented by subclass.

Parameters:

state (dict) – Keyword-mapped states of these objects to encode. Should match structure of output from self._dump_state()

Returns:

encoded + serialized, 1D numerical np.array capturing this objects’s state

Return type:

n-array

class grutopia.core.util.python.UniquelyNamed

Simple class that implements a name property, that must be implemented by a subclass. Note that any @Named entity must be UNIQUE!

property name

Returns: str: Name of this instance. Must be unique!

remove_names(include_all_owned=True, skip_ids=None)

Checks if self.name exists in the global NAMES registry, and deletes it if so. Possibly also iterates through all owned member variables and checks for their corresponding names if @include_all_owned is True.

Parameters:

• include_all_owned (bool) – If True, will iterate through all owned members of this instance and remove their names as well, if they are UniquelyNamed

• skip_ids (None or set of int) – If specified, will skip over any ids in the specified set that are matched to any attributes found (this compares id(attr) to @skip_ids).

class grutopia.core.util.python.UniquelyNamedNonInstance

Identical to UniquelyNamed, but intended for non-instanceable classes

class grutopia.core.util.python.Wrapper(obj)

Base class for all wrapper in OmniGibson

Parameters:

obj (any) – Arbitrary python objects instance to wrap

property unwrapped

Grabs unwrapped objects

Returns:

The unwrapped objects instance

Return type:

any

grutopia.core.util.python.assert_valid_key(key, valid_keys, name=None)

Helper function that asserts that @key is in dictionary @valid_keys keys. If not, it will raise an error.

Parameters:

• key (any) – key to check for in dictionary @dic’s keys

• valid_keys (Iterable) – contains keys should be checked with @key

• name (str or None) – if specified, is the name associated with the key that will be printed out if the key is not found. If None, default is “value”

grutopia.core.util.python.camel_case_to_snake_case(camel_case_text)

Helper function to convert a camel case text to snake case, e.g. “StrawberrySmoothie” -> “strawberry_smoothie”

Parameters:

camel_case_text (str) – Text in camel case

Returns:

snake case text

Return type:

str

grutopia.core.util.python.clear()

Clear state tied to singleton classes

grutopia.core.util.python.create_class_from_registry_and_config(cls_name, cls_registry, cfg, cls_type_descriptor)

Helper function to create a class with str type @cls_name, which should be a valid entry in @cls_registry, using kwargs in dictionary form @cfg to pass to the constructor, with @cls_type_name specified for debugging

Parameters:

• cls_name (str) – Name of the class to create. This should correspond to the actual class type, in string form

• cls_registry (dict) – Class registry. This should map string names of valid classes to create to the actual class type itself

• cfg (dict) – Any keyword arguments to pass to the class constructor

• cls_type_descriptor (str) – Description of the class type being created. This can be any string and is used solely for debugging purposes

Returns:

Created class instance

Return type:

any

grutopia.core.util.python.create_object_from_init_info(init_info)

Create a new objects based on given init info.

Parameters:

init_info (dict) – Nested dictionary that contains an objects’s init information.

Returns:

Newly created objects.

Return type:

any

grutopia.core.util.python.extract_class_init_kwargs_from_dict(cls, dic, copy=False)

Helper function to return a dictionary of key-values that specifically correspond to @cls class’s __init__ constructor method, from @dic which may or may not contain additional, irrelevant kwargs. Note that @dic may possibly be missing certain kwargs as specified by cls.__init__. No error will be raised.

Parameters:

• cls (object) – Class from which to grab __init__ kwargs that will be be used as filtering keys for @dic

• dic (dict) – Dictionary containing multiple key-values

• copy (bool) – If True, will deepcopy all values corresponding to the specified @keys

Returns:

Extracted subset dictionary possibly containing only the specified keys from cls.__init__ and their

corresponding values

Return type:

dict

grutopia.core.util.python.extract_subset_dict(dic, keys, copy=False)

Helper function to extract a subset of dictionary key-values from a current dictionary. Optionally (deep)copies the values extracted from the original @dic if @copy is True.

Parameters:

• dic (dict) – Dictionary containing multiple key-values

• keys (Iterable) – Specific keys to extract from @dic. If the key doesn’t exist in @dic, then the key is skipped

• copy (bool) – If True, will deepcopy all values corresponding to the specified @keys

Returns:

Extracted subset dictionary containing only the specified @keys and their corresponding values

Return type:

dict

grutopia.core.util.python.get_class_init_kwargs(cls)

Helper function to return a list of all valid keyword arguments (excluding “self”) for the given @cls class.

Parameters:

cls (object) – Class from which to grab __init__ kwargs

Returns:

All keyword arguments (excluding “self”) specified by @cls __init__ constructor method

Return type:

list

grutopia.core.util.python.get_uuid(name, n_digits=8)

Helper function to create a unique @n_digits uuid given a unique @name

Parameters:

• name (str) – Name of the objects or class

• n_digits (int) – Number of digits of the uuid, default is 8

Returns:

uuid

Return type:

int

grutopia.core.util.python.meets_minimum_version(test_version, minimum_version)

Verify that @test_version meets the @minimum_version

Parameters:

• test_version (str) – Python package version. Should be, e.g., 0.26.1

• minimum_version (str) – Python package version to test against. Should be, e.g., 0.27.2

Returns:

Whether @test_version meets @minimum_version

Return type:

bool

grutopia.core.util.python.merge_nested_dicts(base_dict, extra_dict, inplace=False, verbose=False)

Iteratively updates @base_dict with values from @extra_dict. Note: This generates a new dictionary!

Parameters:

• base_dict (dict) – Nested base dictionary, which should be updated with all values from @extra_dict

• extra_dict (dict) – Nested extra dictionary, whose values will overwrite corresponding ones in @base_dict

• inplace (bool) – Whether to modify @base_dict in place or not

• verbose (bool) – If True, will print when keys are mismatched

Returns:

Updated dictionary

Return type:

dict

grutopia.core.util.python.save_init_info(func)

Decorator to save the init info of an objects to objects._init_info.

_init_info contains class name and class constructor’s input args.

grutopia.core.util.python.snake_case_to_camel_case(snake_case_text)

Helper function to convert a snake case text to camel case, e.g. “strawberry_smoothie” -> “StrawberrySmoothie”

Parameters:

snake_case_text (str) – Text in snake case

Returns:

camel case text

Return type:

str

grutopia.core.util.python.subclass_factory(name, base_classes, __init__=None, **kwargs)

Programmatically generates a new class type with name @name, subclassing from base classes @base_classes, with corresponding __init__ call @__init__.

NOTE: If __init__ is None (default), the __init__ call from @base_classes will be used instead.

cf. https://stackoverflow.com/questions/15247075/how-can-i-dynamically-create-derived-classes-from-a-base-class

Parameters:

• name (str) – Generated class name

• base_classes (type, or list of type) – Base class(es) to use for generating the subclass

• __init__ (None or function) – Init call to use for the base class when it is instantiated. If None if specified, the newly generated class will automatically inherit the __init__ call from @base_classes

• **kwargs (any) – keyword-mapped parameters to override / set in the child class, where the keys represent the class / instance attribute to modify and the values represent the functions / value to set

string

Submodule containing utilities for transforming strings and regular expressions.

grutopia.core.util.string.callable_to_string(value: Callable) → str

Converts a callable object to a string.

Parameters:

value – A callable object.

Raises:

ValueError – When the input argument is not a callable object.

Returns:

A string representation of the callable object.

grutopia.core.util.string.is_lambda_expression(name: str) → bool

Checks if the input string is a lambda expression.

Parameters:

name – The input string.

Returns:

Whether the input string is a lambda expression.

grutopia.core.util.string.resolve_matching_names(keys: str | Sequence[str], list_of_strings: Sequence[str], preserve_order: bool = False) → tuple[list[int], list[str]]

Match a list of query regular expressions against a list of strings and return the matched indices and names.

When a list of query regular expressions is provided, the function checks each target string against each query regular expression and returns the indices of the matched strings and the matched strings.

If the preserve_order is True, the ordering of the matched indices and names is the same as the order of the provided list of strings. This means that the ordering is dictated by the order of the target strings and not the order of the query regular expressions.

If the preserve_order is False, the ordering of the matched indices and names is the same as the order of the provided list of query regular expressions.

For example, consider the list of strings is [‘a’, ‘b’, ‘c’, ‘d’, ‘e’] and the regular expressions are [‘a|c’, ‘b’]. If preserve_order is False, then the function will return the indices of the matched strings and the strings as: ([0, 1, 2], [‘a’, ‘b’, ‘c’]). When preserve_order is True, it will return them as: ([0, 2, 1], [‘a’, ‘c’, ‘b’]).

Note

The function does not sort the indices. It returns the indices in the order they are found.

Parameters:

• keys – A regular expression or a list of regular expressions to match the strings in the list.

• list_of_strings – A list of strings to match.

• preserve_order – Whether to preserve the order of the query keys in the returned values. Defaults to False.

Returns:

A tuple of lists containing the matched indices and names.

Raises:

• ValueError – When multiple matches are found for a string in the list.

• ValueError – When not all regular expressions are matched.

grutopia.core.util.string.resolve_matching_names_values(data: dict[str, Any], list_of_strings: Sequence[str], preserve_order: bool = False) → tuple[list[int], list[str], list[Any]]

Match a list of regular expressions in a dictionary against a list of strings and return the matched indices, names, and values.

If the preserve_order is True, the ordering of the matched indices and names is the same as the order of the provided list of strings. This means that the ordering is dictated by the order of the target strings and not the order of the query regular expressions.

If the preserve_order is False, the ordering of the matched indices and names is the same as the order of the provided list of query regular expressions.

For example, consider the dictionary is {“a|d|e”: 1, “b|c”: 2}, the list of strings is [‘a’, ‘b’, ‘c’, ‘d’, ‘e’]. If preserve_order is False, then the function will return the indices of the matched strings, the matched strings, and the values as: ([0, 1, 2, 3, 4], [‘a’, ‘b’, ‘c’, ‘d’, ‘e’], [1, 2, 2, 1, 1]). When preserve_order is True, it will return them as: ([0, 3, 4, 1, 2], [‘a’, ‘d’, ‘e’, ‘b’, ‘c’], [1, 1, 1, 2, 2]).

Parameters:

• data – A dictionary of regular expressions and values to match the strings in the list.

• list_of_strings – A list of strings to match.

• preserve_order – Whether to preserve the order of the query keys in the returned values. Defaults to False.

Returns:

A tuple of lists containing the matched indices, names, and values.

Raises:

• TypeError – When the input argument data is not a dictionary.

• ValueError – When multiple matches are found for a string in the dictionary.

• ValueError – When not all regular expressions in the data keys are matched.

grutopia.core.util.string.string_to_callable(name: str) → Callable

Resolves the module and function names to return the function.

Parameters:

name – The function name. The format should be ‘module:attribute_name’ or a lambda expression of format: ‘lambda x: x’.

Raises:

• ValueError – When the resolved attribute is not a function.

• ValueError – When the module cannot be found.

Returns:

The function loaded from the module.

Return type:

Callable

grutopia.core.util.string.to_camel_case(snake_str: str, to: str = 'cC') → str

Converts a string from snake case to camel case.

Parameters:

• snake_str – A string in snake case (i.e. with ‘_’)

• to – Convention to convert string to. Defaults to “cC”.

Raises:

ValueError – Invalid input argument to, i.e. not “cC” or “CC”.

Returns:

A string in camel-case format.

grutopia.core.util.string.to_snake_case(camel_str: str) → str

Converts a string from camel case to snake case.

Parameters:

camel_str – A string in camel case.

Returns:

A string in snake case (i.e. with ‘_’)