SOMA

SOMA provides a native implementation for SOMA-X assets with identity, pose, and corrective controls.

Setup

SOMA downloads automatically on first use from https://huggingface.co/abcamiletto/body-models. The Hugging Face repo records the original SOMA-X Apache 2.0 provenance. To prefetch and save the path:

# Download the SOMA-X assets used by the native SOMA implementation.
body-models download soma

Notes

The native implementation does not require installing py-soma-x.

body-models supports both the legacy SOMA-X NPZ rig asset layout and the SOMA-X 0.2 asset split, where rig data lives in SOMA_template_rig.usda and public-rig derivation metadata lives in SOMA_procedural_transforms.json. With 0.2 assets, the native backend keeps the expanded internal twist-joint rig for skinning while preserving the existing 77-joint public pose API.

The constructor accepts lod="mid", lod="low", or lod="xlo". The hosted assets are preprocessed to keep runtime loading NPZ-only: mid has 18,056 vertices, low has 4,505 vertices, and xlo has 612 vertices.

prepare_identity(..., repose=True) matches the default SOMA-X bind-pose behavior. Pass repose=False to keep the fitted identity rest shape and fitted skeleton before reposing it to the bind pose. Use prepare_identity(..., bind_pose="fit") for the default identity-dependent bind pose. Pass bind_pose="fit_detached" to fit from the current shape without gradients through the fit, or bind_pose="canonical" to use the model bind pose directly.

cache_identity=True can be passed to the constructor for interactive viewers that repeatedly evaluate the same identity with different poses. The default is False, which keeps training and JAX-transformed calls graph-safe unless caching is explicitly requested.

API

body_models.bodies.soma.numpy.SOMA

SOMA(
    model_path=None,
    *,
    model_type="soma",
    lod="mid",
    simplify=1.0,
    rotation_type="axis_angle",
    match_warp=True,
    kernel="scipy",
)

Bases: SkinnedModel

SOMA body model with NumPy backend.

Initialize the SOMA model.

PARAMETER	DESCRIPTION
model_path	Path to model assets, or the default assets when omitted. TYPE: PathLike | None DEFAULT: None
model_type	SOMA identity/model variant to load. TYPE: str DEFAULT: 'soma'
lod	Body mesh level of detail: "mid", "low", or "xlo". TYPE: str DEFAULT: 'mid'
simplify	Mesh simplification factor to apply while loading. TYPE: float DEFAULT: 1.0
rotation_type	Rotation representation expected by pose inputs. TYPE: RotationType DEFAULT: 'axis_angle'
match_warp	Whether to match Warp backend numerical conventions. TYPE: bool DEFAULT: True
kernel	Backend kernel used for forward evaluation. TYPE: Literal['scipy'] DEFAULT: 'scipy'

METHOD	DESCRIPTION
forward_vertices	Compute posed mesh vertices.
forward_skeleton	Compute posed joint transforms.
prepare_identity	Precompute identity-dependent SOMA state for repeated forward passes.
prepare_pose	Precompute local pose-dependent state for repeated forward passes.
joint_index	Resolve a standard joint to this model's native joint index.

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/bodies/soma/numpy.py

def __init__(
    self,
    model_path: PathLike | None = None,
    *,
    model_type: str = "soma",
    lod: str = "mid",
    simplify: float = 1.0,
    rotation_type: RotationType = "axis_angle",
    match_warp: bool = True,
    kernel: Literal["scipy"] = "scipy",
) -> None:
    """Initialize the SOMA model.

    Args:
        model_path: Path to model assets, or the default assets when omitted.
        model_type: SOMA identity/model variant to load.
        lod: Body mesh level of detail: "mid", "low", or "xlo".
        simplify: Mesh simplification factor to apply while loading.
        rotation_type: Rotation representation expected by pose inputs.
        match_warp: Whether to match Warp backend numerical conventions.
        kernel: Backend kernel used for forward evaluation.
    """
    normalized_model_type = model_type.lower()
    if normalized_model_type not in self.VALID_MODEL_TYPES:
        raise ValueError(
            f"Invalid model_type: {model_type}. Supported SOMA model types are {', '.join(self.VALID_MODEL_TYPES)}."
        )
    if rotation_type not in VALID_ROTATION_TYPES:
        raise ValueError(f"Invalid rotation_type: {rotation_type}")
    if kernel not in self.kernels:
        raise ValueError(f"Invalid kernel: {kernel}")
    self.model_type = normalized_model_type
    self.lod = lod.lower()
    self.rotation_type = rotation_type
    self.num_rot_dims = 2 if rotation_type in ("matrix", "rotmat") else 1
    self.match_warp = match_warp
    self._kernel = {"scipy": scipy_backend}[kernel]
    resolved_path, weights = load_model_data_for_lod(model_path, self.lod, simplify=simplify)

    self.parents, self._joint_names = public_joint_metadata(weights)
    self.weights = self._kernel.prepare_data(weights)

    spec = MODEL_TYPE_SPECS[self.model_type]
    self.identity_dim = spec.identity_dim
    self.num_scale_params = spec.num_scale_params
    self._default_identity_value = spec.default_identity_value
    self._identity_source = None
    if spec.asset_dir is not None:
        transfer_data = load_identity_transfer_data(resolved_path, self.model_type)
        self._identity_source = identity_sources.create_identity_source(self.model_type, transfer_data)

common_joints property

common_joints

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

forward_vertices

forward_vertices(
    body_pose,
    head_pose,
    hand_pose,
    global_rotation=None,
    *,
    shape=None,
    scale_params=None,
    identity=None,
    global_translation=None,
    vertex_indices=None,
)

Compute posed mesh vertices.

PARAMETER	DESCRIPTION
body_pose	Local body joint rotations. TYPE: Float[ndarray, 'B 23 N'] | Float[ndarray, 'B 23 3 3']
head_pose	Local head and facial joint rotations. TYPE: Float[ndarray, 'B 5 N'] | Float[ndarray, 'B 5 3 3']
hand_pose	Local hand joint rotations. TYPE: Float[ndarray, 'B 48 N'] | Float[ndarray, 'B 48 3 3']
global_rotation	Global model rotation. TYPE: Float[ndarray, 'B N'] | Float[ndarray, 'B 3 3'] | None DEFAULT: None
shape	Identity coefficients. TYPE: Float[ndarray, '*batch I'] | None DEFAULT: None
scale_params	Per-part scale parameters. TYPE: Float[ndarray, 'B|1 K'] | None DEFAULT: None
identity	Optional output from :meth:prepare_identity. TYPE: SomaIdentity | None DEFAULT: None
global_translation	Global model translation. TYPE: Float[ndarray, 'B 3'] | None DEFAULT: None
vertex_indices	Optional subset of vertices to return. TYPE: Any | None DEFAULT: None

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

Source code in src/body_models/bodies/soma/numpy.py

def forward_vertices(
    self,
    body_pose: Float[np.ndarray, "B 23 N"] | Float[np.ndarray, "B 23 3 3"],
    head_pose: Float[np.ndarray, "B 5 N"] | Float[np.ndarray, "B 5 3 3"],
    hand_pose: Float[np.ndarray, "B 48 N"] | Float[np.ndarray, "B 48 3 3"],
    global_rotation: Float[np.ndarray, "B N"] | Float[np.ndarray, "B 3 3"] | None = None,
    *,
    shape: Float[np.ndarray, "*batch I"] | None = None,
    scale_params: Float[np.ndarray, "B|1 K"] | None = None,
    identity: SomaIdentity | None = None,
    global_translation: Float[np.ndarray, "B 3"] | None = None,
    vertex_indices: Any | None = None,
) -> Float[np.ndarray, "B V 3"]:
    """Compute posed mesh vertices.

    Args:
        body_pose: Local body joint rotations.
        head_pose: Local head and facial joint rotations.
        hand_pose: Local hand joint rotations.
        global_rotation: Global model rotation.
        shape: Identity coefficients.
        scale_params: Per-part scale parameters.
        identity: Optional output from :meth:`prepare_identity`.
        global_translation: Global model translation.
        vertex_indices: Optional subset of vertices to return.

    Returns:
        Posed vertex positions.
    """
    if identity is None:
        assert shape is not None
        batch_shape = tuple(body_pose.shape[: -(self.num_rot_dims + 1)])
        shape = np.broadcast_to(shape, (*batch_shape, shape.shape[-1]))
        if scale_params is not None:
            scale_params = np.broadcast_to(scale_params, (*batch_shape, scale_params.shape[-1]))
        identity = self.prepare_identity(shape, scale_params=scale_params)
    pose = self.prepare_pose(body_pose, head_pose, hand_pose, identity=identity)
    return self._kernel.forward_vertices(
        data=self.weights,
        global_rotation=global_rotation,
        global_translation=global_translation,
        vertex_indices=vertex_indices,
        rotation_type=self.rotation_type,
        rest_vertices=identity["rest_vertices"],
        skinning_transforms=pose["skinning_transforms"],
        pose_offsets=pose["pose_offsets"],
        xp=np,
    )

forward_skeleton

forward_skeleton(
    body_pose,
    head_pose,
    hand_pose,
    global_rotation=None,
    *,
    shape=None,
    scale_params=None,
    identity=None,
    global_translation=None,
    joint_indices=None,
)

Compute posed joint transforms.

PARAMETER	DESCRIPTION
body_pose	Local body joint rotations. TYPE: Float[ndarray, 'B 23 N'] | Float[ndarray, 'B 23 3 3']
head_pose	Local head and facial joint rotations. TYPE: Float[ndarray, 'B 5 N'] | Float[ndarray, 'B 5 3 3']
hand_pose	Local hand joint rotations. TYPE: Float[ndarray, 'B 48 N'] | Float[ndarray, 'B 48 3 3']
global_rotation	Global model rotation. TYPE: Float[ndarray, 'B N'] | Float[ndarray, 'B 3 3'] | None DEFAULT: None
shape	Identity coefficients. TYPE: Float[ndarray, '*batch I'] | None DEFAULT: None
scale_params	Per-part scale parameters. TYPE: Float[ndarray, 'B|1 K'] | None DEFAULT: None
identity	Optional output from :meth:prepare_identity. TYPE: SomaIdentity | None DEFAULT: None
global_translation	Global model translation. TYPE: Float[ndarray, 'B 3'] | None DEFAULT: None
joint_indices	Optional subset of joints to return. TYPE: Any | None DEFAULT: None

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

Source code in src/body_models/bodies/soma/numpy.py

def forward_skeleton(
    self,
    body_pose: Float[np.ndarray, "B 23 N"] | Float[np.ndarray, "B 23 3 3"],
    head_pose: Float[np.ndarray, "B 5 N"] | Float[np.ndarray, "B 5 3 3"],
    hand_pose: Float[np.ndarray, "B 48 N"] | Float[np.ndarray, "B 48 3 3"],
    global_rotation: Float[np.ndarray, "B N"] | Float[np.ndarray, "B 3 3"] | None = None,
    *,
    shape: Float[np.ndarray, "*batch I"] | None = None,
    scale_params: Float[np.ndarray, "B|1 K"] | None = None,
    identity: SomaIdentity | None = None,
    global_translation: Float[np.ndarray, "B 3"] | None = None,
    joint_indices: Any | None = None,
) -> Float[np.ndarray, "B 77 4 4"]:
    """Compute posed joint transforms.

    Args:
        body_pose: Local body joint rotations.
        head_pose: Local head and facial joint rotations.
        hand_pose: Local hand joint rotations.
        global_rotation: Global model rotation.
        shape: Identity coefficients.
        scale_params: Per-part scale parameters.
        identity: Optional output from :meth:`prepare_identity`.
        global_translation: Global model translation.
        joint_indices: Optional subset of joints to return.

    Returns:
        Joint transforms in the model hierarchy.
    """
    if identity is None:
        assert shape is not None
        batch_shape = tuple(body_pose.shape[: -(self.num_rot_dims + 1)])
        shape = np.broadcast_to(shape, (*batch_shape, shape.shape[-1]))
        if scale_params is not None:
            scale_params = np.broadcast_to(scale_params, (*batch_shape, scale_params.shape[-1]))
        identity = self.prepare_identity(shape, scale_params=scale_params, skip_vertices=True)
    pose = self.prepare_pose(body_pose, head_pose, hand_pose, identity=identity, skip_vertices=True)
    return self._kernel.forward_skeleton(
        data=self.weights,
        global_rotation=global_rotation,
        global_translation=global_translation,
        joint_indices=joint_indices,
        rotation_type=self.rotation_type,
        skeleton_transforms=pose["skeleton_transforms"],
        xp=np,
    )

prepare_identity

prepare_identity(
    shape,
    *,
    scale_params=None,
    skip_vertices=False,
    repose=True,
    bind_pose="fit",
)

Precompute identity-dependent SOMA state for repeated forward passes.

Source code in src/body_models/bodies/soma/numpy.py

def prepare_identity(
    self,
    shape: Float[np.ndarray, "*batch I"],
    *,
    scale_params: Float[np.ndarray, "B|1 K"] | None = None,
    skip_vertices: bool = False,
    repose: bool = True,
    bind_pose: core.BindPoseMode = "fit",
) -> SomaIdentity:
    """Precompute identity-dependent SOMA state for repeated forward passes."""
    if self.num_scale_params is None:
        scale_params = None
    elif scale_params is None:
        scale_params = np.zeros((*shape.shape[:-1], self.num_scale_params), dtype=shape.dtype)
    return self._prepare_identity_from_inputs(
        shape,
        scale_params,
        skip_vertices=skip_vertices,
        repose=repose,
        bind_pose=bind_pose,
    )

prepare_pose

prepare_pose(
    body_pose, head_pose, hand_pose, *, identity, skip_vertices=False
)

Precompute local pose-dependent state for repeated forward passes.

Source code in src/body_models/bodies/soma/numpy.py

def prepare_pose(
    self,
    body_pose: Float[np.ndarray, "B 23 N"] | Float[np.ndarray, "B 23 3 3"],
    head_pose: Float[np.ndarray, "B 5 N"] | Float[np.ndarray, "B 5 3 3"],
    hand_pose: Float[np.ndarray, "B 48 N"] | Float[np.ndarray, "B 48 3 3"],
    *,
    identity: SomaIdentity,
    skip_vertices: bool = False,
) -> SomaPreparedPose:
    """Precompute local pose-dependent state for repeated forward passes."""
    batch_shape = tuple(body_pose.shape[: -(self.num_rot_dims + 1)])
    root_rotation = SO3.identity_as(body_pose, batch_dims=batch_shape, rotation_type=self.rotation_type, xp=np)
    pose = pack_pose(np, root_rotation, body_pose, head_pose, hand_pose)
    return self._kernel.prepare_pose(
        self.weights,
        pose,
        rotation_type=self.rotation_type,
        local_joint_translations=identity["local_joint_translations"],
        inverse_bind_transforms=None if skip_vertices else identity["inverse_bind_transforms"],
        skip_vertices=skip_vertices,
        xp=np,
    )

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)