Implementation:Isaac sim IsaacGymEnvs Serializable

Knowledge Sources	IsaacGymEnvs
Domains	Data_Serialization, Framework
Last Updated	2026-02-15 11:00 GMT

Overview

Serializable is an abstract base class and NumpyEncoder is a custom JSON encoder that together provide a framework for serializing and deserializing poselib data objects to JSON and NPY file formats.

Description

The NumpyEncoder class extends json.JSONEncoder to handle numpy data types that are not natively supported by the standard JSON encoder. It converts numpy integer types to Python int, numpy float types to Python float, and numpy arrays to a dictionary representation containing the array data as a nested list, the dtype string, and the shape tuple. A companion json_numpy_obj_hook function reverses this process during deserialization, reconstructing numpy arrays from the dictionary representation.

The Serializable class provides an abstract interface for objects that need to be persisted to disk. Subclasses must implement from_dict (a classmethod that constructs an instance from an OrderedDict) and to_dict (an instance method that converts the object to an OrderedDict). The base class provides from_file and to_file methods that handle reading from and writing to both JSON and NPY file formats. When writing, the class name is embedded in the serialized dictionary under the __name__ key; when reading, this name is verified to ensure the file contains data for the expected class.

The module also includes a global TENSOR_CLASS registry with register and _get_cls functions, enabling dynamic registration and lookup of tensor classes by name. This supports the poselib framework's ability to work with different tensor backends.

Usage

Use Serializable as a base class when creating poselib data objects (such as skeleton trees, skeleton states, or skeleton motions) that need to be saved to and loaded from disk. Use NumpyEncoder when custom JSON serialization of numpy types is needed outside the Serializable framework.

Code Reference

Source Location

• Repository: IsaacGymEnvs
• File: isaacgymenvs/tasks/amp/poselib/poselib/core/backend/abstract.py
• Lines: 55-150

Signature

class NumpyEncoder(json.JSONEncoder):
    def default(self, obj):
        ...

def json_numpy_obj_hook(dct):
    ...

class Serializable:
    @abstractclassmethod
    def from_dict(cls, dict_repr, *args, **kwargs):
        ...

    @abstractmethod
    def to_dict(self):
        ...

    @classmethod
    def from_file(cls, path, *args, **kwargs):
        ...

    def to_file(self, path: str) -> None:
        ...

Import

from isaacgymenvs.tasks.amp.poselib.poselib.core.backend.abstract import Serializable

I/O Contract

Inputs

Name	Type	Required	Description
dict_repr	OrderedDict	Yes	Ordered dictionary representation of the object (for from_dict)
path	str	Yes	File path ending in .json or .npy (for from_file and to_file)
obj	numpy type	Yes	A numpy integer, float, or ndarray to encode (for NumpyEncoder.default)

Outputs

Name	Type	Description
instance	Serializable subclass	Deserialized object instance from from_file or from_dict
dict_repr	OrderedDict	Serialized dictionary from to_dict
file	.json or .npy file	Persisted file written by to_file

Usage Examples

from isaacgymenvs.tasks.amp.poselib.poselib.core.backend.abstract import Serializable
from collections import OrderedDict

# Example subclass implementing Serializable
class MyPoseData(Serializable):
    def __init__(self, joint_positions):
        self.joint_positions = joint_positions

    @classmethod
    def from_dict(cls, dict_repr, *args, **kwargs):
        return cls(joint_positions=dict_repr["joint_positions"])

    def to_dict(self):
        return OrderedDict(joint_positions=self.joint_positions)

# Save to file
data = MyPoseData(joint_positions=np.array([1.0, 2.0, 3.0]))
data.to_file("/path/to/pose_data.json")

# Load from file
loaded_data = MyPoseData.from_file("/path/to/pose_data.json")