G1

G1 is a rigid articulated Unitree G1 model with STL link meshes attached to the Kimodo 34-joint skeleton.

Setup

G1 downloads automatically on first use. To prefetch and save the path:

# Download the Unitree G1 XML and link meshes.
body-models download g1

When passed manually, model_path should contain xml/g1.xml and meshes/g1/*.STL.

Notes

G1 is a rigid articulated model, so it does not define skin_weights. Use forward_links, link_mesh, or joint_meshes when rendering or inspecting individual STL links.

API

body_models.robots.g1.numpy.G1

G1(model_path=None, *, rotation_type='rotmat', convention='soma')

Bases: BodyModel

Unitree G1 as rigid STL links attached to the Kimodo 34-joint skeleton.

Initialize the G1 model.

PARAMETER	DESCRIPTION
model_path	Path to model assets, or the default assets when omitted. TYPE: Path | str | None DEFAULT: None
rotation_type	Rotation representation expected by pose inputs. TYPE: RotationType DEFAULT: 'rotmat'
convention	Skeleton convention used when loading rigid model data. TYPE: Convention DEFAULT: 'soma'

METHOD	DESCRIPTION
forward_skeleton	Compute posed joint transforms.
forward_vertices	Compute posed mesh vertices.
joint_index	Resolve a standard joint to this model's native joint index.
prepare_skinning	Pack prepared model state into renderer-ready skinning inputs.

ATTRIBUTE	DESCRIPTION
common_joints	Common anatomical joints mapped to this model's native joint names. TYPE: Mapping[Joint, str]

Source code in src/body_models/robots/g1/numpy.py

def __init__(
    self,
    model_path: Path | str | None = None,
    *,
    rotation_type: core.RotationType = "rotmat",
    convention: core.Convention = "soma",
) -> None:
    """Initialize the G1 model.

    Args:
        model_path: Path to model assets, or the default assets when omitted.
        rotation_type: Rotation representation expected by pose inputs.
        convention: Skeleton convention used when loading rigid model data.
    """
    if rotation_type not in core.VALID_ROTATION_TYPES:
        raise ValueError(f"Invalid rotation_type: {rotation_type}")
    self.rotation_type = rotation_type
    self.num_rot_dims = 2 if rotation_type in ("matrix", "rotmat") else 1
    self.convention = convention
    self.weights = load_model_data(model_path, convention=convention)

common_joints property

common_joints

Common anatomical joints mapped to this model's native joint names.

forward_skeleton

forward_skeleton(
    body_pose,
    global_translation=None,
    *,
    global_rotation=None,
    joint_indices=None,
)

Compute posed joint transforms.

PARAMETER	DESCRIPTION
body_pose	Local body joint rotations. TYPE: Float[ndarray, 'B Q N'] | Float[ndarray, 'B Q 3 3']
global_translation	Global model translation. TYPE: Float[ndarray, 'B 3'] | None DEFAULT: None
global_rotation	Global model rotation. TYPE: Float[ndarray, 'B N'] | Float[ndarray, 'B 3 3'] | None DEFAULT: None
joint_indices	Optional subset of joints to return. TYPE: list[int] | None DEFAULT: None

RETURNS	DESCRIPTION
Float[ndarray, 'B J 4 4']	Joint transforms in the model hierarchy.

Source code in src/body_models/robots/g1/numpy.py

def forward_skeleton(
    self,
    body_pose: Float[np.ndarray, "B Q N"] | Float[np.ndarray, "B Q 3 3"],
    global_translation: Float[np.ndarray, "B 3"] | None = None,
    *,
    global_rotation: Float[np.ndarray, "B N"] | Float[np.ndarray, "B 3 3"] | None = None,
    joint_indices: list[int] | None = None,
) -> Float[np.ndarray, "B J 4 4"]:
    """Compute posed joint transforms.

    Args:
        body_pose: Local body joint rotations.
        global_translation: Global model translation.
        global_rotation: Global model rotation.
        joint_indices: Optional subset of joints to return.

    Returns:
        Joint transforms in the model hierarchy.
    """
    return backend.forward_skeleton(
        self.weights,
        body_pose,
        global_translation,
        global_rotation=global_rotation,
        joint_indices=joint_indices,
        rotation_type=self.rotation_type,
    )

forward_vertices

forward_vertices(
    body_pose,
    global_translation=None,
    *,
    global_rotation=None,
    vertex_indices=None,
)

Compute posed mesh vertices.

PARAMETER	DESCRIPTION
body_pose	Local body joint rotations. TYPE: Float[ndarray, 'B Q N'] | Float[ndarray, 'B Q 3 3']
global_translation	Global model translation. TYPE: Float[ndarray, 'B 3'] | None DEFAULT: None
global_rotation	Global model rotation. TYPE: Float[ndarray, 'B N'] | Float[ndarray, 'B 3 3'] | None DEFAULT: None
vertex_indices	Optional subset of vertices to return. TYPE: list[int] | None DEFAULT: None

RETURNS	DESCRIPTION
Float[ndarray, 'B V 3']	Posed vertex positions.

Source code in src/body_models/robots/g1/numpy.py

def forward_vertices(
    self,
    body_pose: Float[np.ndarray, "B Q N"] | Float[np.ndarray, "B Q 3 3"],
    global_translation: Float[np.ndarray, "B 3"] | None = None,
    *,
    global_rotation: Float[np.ndarray, "B N"] | Float[np.ndarray, "B 3 3"] | None = None,
    vertex_indices: list[int] | None = None,
) -> Float[np.ndarray, "B V 3"]:
    """Compute posed mesh vertices.

    Args:
        body_pose: Local body joint rotations.
        global_translation: Global model translation.
        global_rotation: Global model rotation.
        vertex_indices: Optional subset of vertices to return.

    Returns:
        Posed vertex positions.
    """
    return backend.forward_vertices(
        self.weights,
        body_pose,
        global_translation,
        global_rotation=global_rotation,
        vertex_indices=vertex_indices,
        rotation_type=self.rotation_type,
    )

joint_index

joint_index(joint)

Resolve a standard joint to this model's native joint index.

Source code in src/body_models/base.py

def joint_index(self, joint: Joint) -> int:
    """Resolve a standard joint to this model's native joint index."""
    if not isinstance(joint, Joint):
        raise TypeError("joint_index() expects a body_models.Joint; use joint_names.index(...) for native names.")
    try:
        native_name = self.common_joints[joint]
    except KeyError as exc:
        raise KeyError(f"{self.__class__.__name__} has no standard joint {joint.value!r}") from exc
    return self.joint_names.index(native_name)

prepare_skinning

prepare_skinning(*, identity, pose)

Pack prepared model state into renderer-ready skinning inputs.

Source code in src/body_models/base.py

def prepare_skinning(self, *, identity: Mapping[str, Any], pose: Mapping[str, Any]) -> SkinningPayload:
    """Pack prepared model state into renderer-ready skinning inputs."""
    if self.is_rigid_body:
        raise NotImplementedError(f"{self.__class__.__name__} is rigid and does not support skinning.")

    skinning: SkinningPayload = {
        "rest_vertices": identity["rest_vertices"],
        "skinning_transforms": pose["skinning_transforms"],
        "skin_weights": self.skin_weights,
        "faces": self.faces,
    }
    if "pose_offsets" in pose:
        skinning["pose_offsets"] = pose["pose_offsets"]
    return skinning