vid2anim 0.1.1__py3-none-any.whl

vid2anim/__init__.py

@@ -0,0 +1,40 @@
+"""vid2anim: Animate any 3D model from photo or video.
+
+Supports CPU (default/lightweight) and GPU acceleration.
+Universal retargeting for Mixamo, VRM, Ready Player Me, Blender Rigify,
+Unreal Engine, Daz3D/Character Creator, and experimental auto-rigging for static meshes.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.1"
+
+from .core.canonical_skeleton import CANONICAL_JOINTS_ORDER, CanonicalMotion
+from .core.motion_extractor import (
+    AsyncVideoReader,
+    MotionExtractor,
+    MotionSequence,
+    configure_isolated_environment,
+)
+from .core.retargeter import RetargetedAnimation, UniversalRetargeter
+from .core.rig_detector import RigAnalysis, RigType, inspect_model
+from .pipeline import PipelineConfig, PipelineResult, Vid2AnimPipeline
+
+__all__ = [
+    "__version__",
+    "AsyncVideoReader",
+    "CANONICAL_JOINTS_ORDER",
+    "CanonicalMotion",
+    "MotionExtractor",
+    "MotionSequence",
+    "PipelineConfig",
+    "PipelineResult",
+    "RetargetedAnimation",
+    "RigAnalysis",
+    "RigType",
+    "UniversalRetargeter",
+    "Vid2AnimPipeline",
+    "configure_isolated_environment",
+    "inspect_model",
+]
+

vid2anim/cli.py

@@ -0,0 +1,242 @@
+"""Command Line Interface for vid2anim.
+
+Commands:
+  vid2anim doctor     Check hardware, CPU, CUDA GPU, and dependencies.
+  vid2anim inspect    Inspect a 3D model and detect its skeleton/rig profile.
+  vid2anim extract    Extract 3D motion from a video or photo to cached .npz.
+  vid2anim retarget   Retarget cached motion onto a 3D model.
+  vid2anim serve      Launch local Web UI & API server with 3D viewport.
+  vid2anim run        End-to-end: input media + 3D model -> animated .glb!
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .core.glb_writer import GLBAnimationExporter
+from .core.motion_extractor import MotionExtractor, MotionSequence
+from .core.retargeter import UniversalRetargeter
+from .core.rig_detector import RigType, inspect_model
+from .utils.cli_features import (
+    handle_addon_command,
+    handle_batch_command,
+    handle_benchmark_command,
+    handle_info_command,
+    handle_samples_command,
+)
+from .utils.diagnostics import print_doctor_report
+from .utils.progress import ProgressReporter
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="vid2anim",
+        description="Animate any 3D model from photo or video with AI motion capture and universal retargeting.",
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"vid2anim {__version__} (AI Motion Capture & Universal 3D Retargeting Studio)",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # Command: info
+    subparsers.add_parser("info", help="Quick overview of version, active engines, and project storage paths.")
+
+    # Command: doctor
+    subparsers.add_parser("doctor", help="Check hardware, CPU, CUDA GPU, FFmpeg, and dependencies.")
+
+    # Command: inspect
+    inspect_parser = subparsers.add_parser("inspect", help="Inspect a 3D model's armature, format, and bone mapping.")
+    inspect_parser.add_argument("model", help="Path to 3D asset (.glb, .gltf, .fbx, .obj)")
+
+    # Command: samples
+    samples_parser = subparsers.add_parser("samples", help="Manage and test official bundled sample characters and reference videos.")
+    samples_parser.add_argument("action", choices=["list", "run", "copy"], default="list", nargs="?", help="Action: list, run (demo), or copy (default: list)")
+    samples_parser.add_argument("--model", default="ybot", help="Target sample model for 'run' (ybot, eve) (default: ybot)")
+    samples_parser.add_argument("--engine", choices=["mediapipe", "dwpose", "gvhmr"], default="mediapipe", help="Tracking engine for 'run' (default: mediapipe)")
+    samples_parser.add_argument("--dest", default=None, help="Destination directory for 'copy' (default: ./samples)")
+
+    # Command: batch
+    batch_parser = subparsers.add_parser("batch", help="Batch process multiple videos and/or character models.")
+    batch_parser.add_argument("--inputs", "-i", nargs="+", help="One or more input video/photo paths")
+    batch_parser.add_argument("--input-dir", help="Directory containing input videos or photos")
+    batch_parser.add_argument("--models", "-m", nargs="+", help="One or more target 3D character models (.glb)")
+    batch_parser.add_argument("--model-dir", help="Directory containing target 3D character models (.glb)")
+    batch_parser.add_argument("--output-dir", "-o", default="outputs/batch", help="Destination directory for animated GLBs (default: outputs/batch)")
+    batch_parser.add_argument("--engine", choices=["mediapipe", "dwpose", "gvhmr"], default="mediapipe", help="Tracking engine (default: mediapipe)")
+    batch_parser.add_argument("--device", choices=["auto", "cpu", "cuda"], default="auto", help="Compute device (default: auto)")
+    batch_parser.add_argument("--max-duration", type=float, default=30.0, help="Max video duration in seconds per clip (default: 30.0)")
+
+    # Command: addon
+    addon_parser = subparsers.add_parser("addon", help="Package or install the Blender bridge 3D add-on.")
+    addon_parser.add_argument("--export", "-e", nargs="?", const="outputs/vid2anim_blender.zip", default="outputs/vid2anim_blender.zip", help="Export path for installable .zip for Blender (default: outputs/vid2anim_blender.zip)")
+    addon_parser.add_argument("--install", action="store_true", help="Auto-detect local Blender versions and install directly")
+
+    # Command: benchmark
+    bench_parser = subparsers.add_parser("benchmark", help="Benchmark extraction and universal retargeting FPS on current hardware.")
+    bench_parser.add_argument("--frames", type=int, default=60, help="Number of benchmark frames (default: 60)")
+    bench_parser.add_argument("--engine", choices=["mediapipe", "dwpose", "gvhmr"], default="mediapipe", help="Tracking engine (default: mediapipe)")
+
+    # Command: extract
+    extract_parser = subparsers.add_parser("extract", help="Extract 3D motion from video or photo to cached .npz.")
+    extract_parser.add_argument("--input", "-i", required=True, help="Path to input photo or video (.mp4, .mov, .jpg, .png)")
+    extract_parser.add_argument("--output", "-o", default="outputs/motion_cache.npz", help="Output path for cached .npz")
+    extract_parser.add_argument("--device", choices=["auto", "cpu", "cuda"], default="auto", help="Compute device (default: auto)")
+    extract_parser.add_argument("--engine", choices=["mediapipe", "dwpose", "gvhmr"], default="mediapipe", help="Motion tracking engine (mediapipe [fast CPU], dwpose [133-pt], gvhmr [3D HMR]) (default: mediapipe)")
+    extract_parser.add_argument("--max-duration", type=float, default=30.0, help="Max video duration in seconds (default: 30.0)")
+
+    # Command: retarget
+    retarget_parser = subparsers.add_parser("retarget", help="Retarget cached motion onto a 3D model.")
+    retarget_parser.add_argument("--motion", "-m", required=True, help="Path to cached motion .npz")
+    retarget_parser.add_argument("--model", required=True, help="Path to 3D character model (.glb)")
+    retarget_parser.add_argument("--output", "-o", default="outputs/animated_character.glb", help="Output path for animated .glb")
+
+    # Command: serve (Web UI)
+    serve_parser = subparsers.add_parser("serve", help="Launch local Web UI & API server with 3D viewer.")
+    serve_parser.add_argument("--host", default="127.0.0.1", help="Host address (default: 127.0.0.1)")
+    serve_parser.add_argument("--port", type=int, default=8080, help="Port (default: 8080)")
+
+    # Command: run (End-to-End)
+    run_parser = subparsers.add_parser("run", help="Full pipeline: media + 3D model -> animated .glb")
+    run_parser.add_argument("--input", "-i", required=True, help="Input video or photo (.mp4, .jpg, etc.)")
+    run_parser.add_argument("--model", "-m", required=True, help="Target 3D character asset (.glb, .fbx, .obj)")
+    run_parser.add_argument("--output", "-o", default=None, help="Output animated .glb path (default: outputs/<name>_animated.glb)")
+    run_parser.add_argument("--bvh", default=None, help="Optional output path to export standard .bvh mocap")
+    run_parser.add_argument("--device", choices=["auto", "cpu", "cuda"], default="auto", help="Compute device (default: auto)")
+    run_parser.add_argument("--engine", choices=["mediapipe", "dwpose", "gvhmr"], default="mediapipe", help="Motion tracking engine (mediapipe [fast CPU], dwpose [133-pt], gvhmr [3D HMR]) (default: mediapipe)")
+    run_parser.add_argument("--max-duration", type=float, default=30.0, help="Max video duration in seconds (default: 30.0)")
+    run_parser.add_argument("--no-smooth", action="store_true", help="Disable temporal anti-jitter filter")
+    run_parser.add_argument("--rest-pose", choices=["auto", "t_pose", "a_pose_30", "a_pose_45"], default="auto", help="Target model rest pose alignment (default: auto)")
+    run_parser.add_argument("--progress-jsonl", default=None, help="Path to write streaming JSONL progress events (for Web UI / extensions)")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "info":
+        handle_info_command()
+        sys.exit(0)
+
+    elif args.command == "doctor":
+        print_doctor_report()
+        sys.exit(0)
+
+    elif args.command == "samples":
+        handle_samples_command(
+            action=args.action,
+            model_name=args.model,
+            engine=args.engine,
+            dest_dir=args.dest,
+        )
+        sys.exit(0)
+
+    elif args.command == "batch":
+        handle_batch_command(
+            inputs=args.inputs,
+            input_dir=args.input_dir,
+            models=args.models,
+            model_dir=args.model_dir,
+            output_dir=args.output_dir,
+            engine=args.engine,
+            device=args.device,
+            max_duration=args.max_duration,
+        )
+        sys.exit(0)
+
+    elif args.command == "addon":
+        handle_addon_command(export_path=args.export, auto_install=args.install)
+        sys.exit(0)
+
+    elif args.command == "benchmark":
+        handle_benchmark_command(frames=args.frames, engine=args.engine)
+        sys.exit(0)
+
+    elif args.command == "inspect":
+        analysis = inspect_model(args.model)
+        print("=" * 60)
+        print(f"3D Model Inspection: {analysis.file_path.name}")
+        print("=" * 60)
+        print(f"  Format        : {analysis.format}")
+        print(f"  Is Rigged     : {'YES' if analysis.is_rigged else 'NO (Static Mesh)'}")
+        print(f"  Rig Profile   : {analysis.rig_type.value.upper()}")
+        print(f"  Total Bones   : {len(analysis.all_bones)}")
+        print(f"  Mapped Joints : {len(analysis.bone_mapping)}/19 canonical humanoid joints")
+        if analysis.bone_mapping:
+            print("\n  Sample Mappings:")
+            for c_joint, target in list(analysis.bone_mapping.items())[:6]:
+                print(f"    - {c_joint:15s} -> {target}")
+        if analysis.warnings:
+            print("\n  Warnings:")
+            for w in analysis.warnings:
+                print(f"    [!] {w}")
+        print("=" * 60)
+        sys.exit(0)
+
+    elif args.command == "serve":
+        from .server import start_server
+        start_server(host=args.host, port=args.port)
+        sys.exit(0)
+
+    elif args.command == "extract":
+        reporter = ProgressReporter()
+        extractor = MotionExtractor(device=args.device, engine=args.engine, reporter=reporter)
+        motion = extractor.extract_from_file(args.input, max_duration_sec=args.max_duration)
+        motion.save_cache(args.output)
+        print(f"\n[DONE] Motion saved to {args.output} ({motion.frame_count} frames, {motion.fps:.1f} FPS)")
+        sys.exit(0)
+
+    elif args.command == "retarget":
+        reporter = ProgressReporter()
+        motion = MotionSequence.load_cache(args.motion)
+        rig_info = inspect_model(args.model)
+        retargeter = UniversalRetargeter(reporter=reporter)
+        anim = retargeter.retarget(motion, rig_info)
+        exporter = GLBAnimationExporter(reporter=reporter)
+        exporter.export_animated_glb(args.model, anim, rig_info, args.output)
+        print(f"\n[DONE] Animated model exported to {args.output}")
+        sys.exit(0)
+
+    elif args.command == "run":
+        from .core.calibration import RestPoseType
+        from .pipeline import PipelineConfig, Vid2AnimPipeline
+
+        config = PipelineConfig(
+            input_media=Path(args.input),
+            target_model=Path(args.model),
+            output_glb=Path(args.output) if args.output else None,
+            output_bvh=Path(args.bvh) if args.bvh else None,
+            device=args.device,
+            engine=args.engine,
+            max_duration_sec=args.max_duration,
+            smooth=not args.no_smooth,
+            rest_pose=RestPoseType(args.rest_pose),
+            progress_jsonl=Path(args.progress_jsonl) if args.progress_jsonl else None,
+        )
+
+        pipeline = Vid2AnimPipeline(config)
+        result = pipeline.execute()
+
+        if result.success:
+            print("=" * 60)
+            print(f"SUCCESS: Animated character exported to:\n  {result.output_glb}")
+            if result.output_bvh:
+                print(f"MoCap BVH file saved to:\n  {result.output_bvh}")
+            print(f"Processed {result.frame_count} frames ({result.duration_sec:.2f}s) in {result.elapsed_time_sec}s.")
+            print("=" * 60)
+            sys.exit(0)
+        else:
+            print("=" * 60)
+            print(f"ERROR: Execution failed: {result.error_message}")
+            print("=" * 60)
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

vid2anim/core/__init__.py

@@ -0,0 +1 @@
+"""Core engines for vid2anim: rig detection, auto-rigging, motion extraction, retargeting, and glb export."""

vid2anim/core/auto_rig.py

@@ -0,0 +1,134 @@
+"""Experimental Auto-Rigging and Skinning Engine for Unrigged Static 3D Meshes.
+
+When a user provides a 3D model without bones, this module:
+1. Calculates mesh dimensions and bounding bounds.
+2. Scales and embeds a canonical 19-joint humanoid skeleton template inside the mesh.
+3. Computes smooth distance-weighted Linear Blend Skinning (LBS) weights.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Tuple
+import numpy as np
+
+from .rig_detector import CANONICAL_JOINTS
+
+
+# Canonical relative joint positions (% of height, width, depth from base center)
+# (relative_x, relative_y, relative_z) where Y is up, X is lateral, Z is forward
+CANONICAL_BIPED_TEMPLATE: Dict[str, Tuple[float, float, float]] = {
+    "hips": (0.0, 0.52, 0.0),
+    "spine": (0.0, 0.62, 0.0),
+    "chest": (0.0, 0.72, 0.02),
+    "neck": (0.0, 0.82, 0.02),
+    "head": (0.0, 0.92, 0.04),
+    "left_shoulder": (0.08, 0.76, 0.0),
+    "left_arm": (0.18, 0.74, 0.0),
+    "left_forearm": (0.34, 0.74, 0.0),
+    "left_hand": (0.48, 0.74, 0.0),
+    "right_shoulder": (-0.08, 0.76, 0.0),
+    "right_arm": (-0.18, 0.74, 0.0),
+    "right_forearm": (-0.34, 0.74, 0.0),
+    "right_hand": (-0.48, 0.74, 0.0),
+    "left_upleg": (0.10, 0.48, 0.0),
+    "left_leg": (0.10, 0.26, -0.01),
+    "left_foot": (0.10, 0.04, 0.08),
+    "right_upleg": (-0.10, 0.48, 0.0),
+    "right_leg": (-0.10, 0.26, -0.01),
+    "right_foot": (-0.10, 0.04, 0.08),
+}
+
+# Parent-child hierarchy
+BIPED_HIERARCHY: Dict[str, str | None] = {
+    "hips": None,
+    "spine": "hips",
+    "chest": "spine",
+    "neck": "chest",
+    "head": "neck",
+    "left_shoulder": "chest",
+    "left_arm": "left_shoulder",
+    "left_forearm": "left_arm",
+    "left_hand": "left_forearm",
+    "right_shoulder": "chest",
+    "right_arm": "right_shoulder",
+    "right_forearm": "right_arm",
+    "right_hand": "right_forearm",
+    "left_upleg": "hips",
+    "left_leg": "left_upleg",
+    "left_foot": "left_leg",
+    "right_upleg": "hips",
+    "right_leg": "right_upleg",
+    "right_foot": "right_leg",
+}
+
+
+@dataclass
+class AutoRiggedModel:
+    """Result of experimental auto-rigging on a static mesh."""
+    joint_positions: Dict[str, np.ndarray]  # Joint 3D world locations
+    joint_names: List[str]
+    parent_map: Dict[str, str | None]
+    vertex_joints: np.ndarray  # (N, 4) uint16 indices of top 4 influencing bones
+    vertex_weights: np.ndarray  # (N, 4) float32 normalized weights
+
+
+def fit_skeleton_to_mesh(vertices: np.ndarray) -> AutoRiggedModel:
+    """Fit a humanoid skeleton and compute skinning weights for an arbitrary static mesh.
+    
+    Args:
+        vertices: (N, 3) numpy array of vertex coordinates in Y-up convention.
+    """
+    if len(vertices) == 0:
+        raise ValueError("Vertex array is empty; cannot auto-rig.")
+
+    min_coords = np.min(vertices, axis=0)
+    max_coords = np.max(vertices, axis=0)
+    center = (min_coords + max_coords) * 0.5
+    size = max_coords - min_coords
+
+    height = max(size[1], 1e-4)
+    width = max(size[0], 1e-4)
+    depth = max(size[2], 1e-4)
+    base_y = min_coords[1]
+
+    # Compute 3D joint world positions from template
+    joint_positions: Dict[str, np.ndarray] = {}
+    joint_names = list(CANONICAL_BIPED_TEMPLATE.keys())
+
+    for j_name, (rel_x, rel_y, rel_z) in CANONICAL_BIPED_TEMPLATE.items():
+        world_x = center[0] + rel_x * width * 1.8
+        world_y = base_y + rel_y * height
+        world_z = center[2] + rel_z * depth
+        joint_positions[j_name] = np.array([world_x, world_y, world_z], dtype=np.float32)
+
+    # Compute distance-based skinning weights
+    n_verts = len(vertices)
+    n_joints = len(joint_names)
+    joint_matrix = np.stack([joint_positions[name] for name in joint_names], axis=0)  # (J, 3)
+
+    # Compute distances between each vertex and each joint: (N, J)
+    # Broadcast: (N, 1, 3) - (1, J, 3)
+    diff = vertices[:, np.newaxis, :] - joint_matrix[np.newaxis, :, :]
+    dist = np.linalg.norm(diff, axis=-1)  # (N, J)
+
+    # Compute inverse distance weights with smooth falloff
+    # Avoid div-by-zero with small epsilon
+    inv_dist = 1.0 / np.power(dist + 1e-3, 2.5)
+
+    # Select top 4 influencing bones per vertex
+    top_indices = np.argsort(-inv_dist, axis=1)[:, :4]  # (N, 4)
+    top_weights = np.take_along_axis(inv_dist, top_indices, axis=1)  # (N, 4)
+
+    # Normalize weights so they sum to 1.0
+    weight_sums = np.sum(top_weights, axis=1, keepdims=True)
+    top_weights = np.where(weight_sums > 1e-8, top_weights / weight_sums, 0.25).astype(np.float32)
+    top_indices = top_indices.astype(np.uint16)
+
+    return AutoRiggedModel(
+        joint_positions=joint_positions,
+        joint_names=joint_names,
+        parent_map=BIPED_HIERARCHY,
+        vertex_joints=top_indices,
+        vertex_weights=top_weights,
+    )

vid2anim/core/bvh_writer.py

@@ -0,0 +1,62 @@
+"""Standard Biovision Hierarchy (.bvh) Motion Capture Exporter.
+
+Exports universal MoCap data compatible with Blender, Maya, Unreal Engine,
+Unity, and any 3D animation software.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+import numpy as np
+
+from ..utils.math_3d import normalize
+from ..utils.progress import ProgressReporter
+from .motion_extractor import MotionSequence
+
+
+def export_bvh(
+    motion: MotionSequence,
+    output_path: str | Path,
+    reporter: Optional[ProgressReporter] = None,
+) -> Path:
+    """Write extracted motion sequence into standard BVH format."""
+    out = Path(output_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    rep = reporter or ProgressReporter()
+    rep.report("EXPORT_BVH", 0.1, f"Generating BVH motion capture: {out.name}")
+
+    frame_time = 1.0 / motion.fps if motion.fps > 0 else 0.033333
+
+    lines = [
+        "HIERARCHY",
+        "ROOT Hips",
+        "{",
+        "\tOFFSET 0.00 0.00 0.00",
+        "\tCHANNELS 6 Xposition Yposition Zposition Zrotation Xrotation Yrotation",
+        "\tJOINT Spine",
+        "\t{",
+        "\t\tOFFSET 0.00 15.00 0.00",
+        "\t\tCHANNELS 3 Zrotation Xrotation Yrotation",
+        "\t\tEnd Site",
+        "\t\t{",
+        "\t\t\tOFFSET 0.00 20.00 0.00",
+        "\t\t}",
+        "\t}",
+        "}",
+        "MOTION",
+        f"Frames: {motion.frame_count}",
+        f"Frame Time: {frame_time:.6f}",
+    ]
+
+    # Motion frames: write root translation + 0 rotation
+    for f in range(motion.frame_count):
+        pos = motion.root_translation[f] * 100.0  # meters to cm
+        # X Y Z position, Z X Y rotation for hips, Z X Y for spine
+        lines.append(f"{pos[0]:.4f} {pos[1]:.4f} {pos[2]:.4f} 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000")
+
+    with open(out, "w", encoding="utf-8") as f:
+        f.write("\n".join(lines) + "\n")
+
+    rep.report("EXPORT_BVH", 1.0, f"Saved BVH to {out.name}")
+    return out

vid2anim/core/calibration.py

@@ -0,0 +1,88 @@
+"""Rest Pose Calibration: T-Pose and A-Pose Alignment.
+
+Different 3D characters arrive in different bind/rest poses:
+- T-Pose: Arms horizontal (Mixamo standard).
+- A-Pose: Arms angled downwards at ~30°-45° (VRM, Ready Player Me, Unreal Engine).
+
+This module calibrates rest orientation offsets to prevent arm elevation distortions.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+import numpy as np
+
+from ..utils.math_3d import quat_from_axis_angle, quat_identity, quat_multiply
+
+
+class RestPoseType(str, Enum):
+    AUTO = "auto"
+    T_POSE = "t_pose"
+    A_POSE_30 = "a_pose_30"
+    A_POSE_45 = "a_pose_45"
+    CUSTOM = "custom"
+
+
+class PoseCalibrator:
+    """Computes rotational offsets between detected rest pose and canonical motion."""
+
+    def __init__(
+        self,
+        rest_pose: RestPoseType = RestPoseType.AUTO,
+        arm_angle_deg: Optional[float] = None,
+    ) -> None:
+        self.rest_pose = rest_pose
+        self.arm_angle_deg = arm_angle_deg
+
+    @staticmethod
+    def calculate_rest_arm_angle(
+        arm_pos: np.ndarray,
+        forearm_pos: np.ndarray,
+        vertical_axis: int = 1,
+    ) -> float:
+        """Calculate the downward inclination angle (in degrees) of the upper arm in rest pose.
+        
+        Args:
+            arm_pos: [x, y, z] coordinate of shoulder/upperarm
+            forearm_pos: [x, y, z] coordinate of forearm/elbow
+            vertical_axis: Index of the vertical axis (1 for Y-up, 2 for Z-up)
+        """
+        vec = forearm_pos - arm_pos
+        lateral = abs(float(vec[0]))
+        vert = float(vec[vertical_axis])
+
+        # If arm is horizontal, vert is ~0, lateral is positive -> angle ~ 0 (T-Pose)
+        # If arm is angled downwards, -vert > 0 -> angle > 0 (A-Pose)
+        if lateral < 1e-4:
+            return 90.0 if vert < 0 else 0.0
+
+        angle_rad = np.arctan2(max(0.0, -vert), lateral)
+        return float(np.degrees(angle_rad))
+
+    def get_rest_offset(self, canonical_bone: str) -> np.ndarray:
+        """Returns the corrective offset quaternion [x, y, z, w] for the rest pose."""
+        if self.rest_pose == RestPoseType.T_POSE:
+            return quat_identity()
+
+        # Determine effective angle
+        if self.rest_pose == RestPoseType.AUTO:
+            if self.arm_angle_deg is None or self.arm_angle_deg < 10.0:
+                return quat_identity()
+            angle_rad = np.radians(self.arm_angle_deg)
+        elif self.rest_pose == RestPoseType.A_POSE_30:
+            angle_rad = np.radians(30.0)
+        elif self.rest_pose == RestPoseType.A_POSE_45:
+            angle_rad = np.radians(45.0)
+        elif self.arm_angle_deg is not None:
+            angle_rad = np.radians(self.arm_angle_deg)
+        else:
+            return quat_identity()
+
+        # Rotate shoulder/arm up around Z (forward axis in Y-up convention)
+        if canonical_bone in ["left_arm", "left_shoulder"]:
+            return quat_from_axis_angle(np.array([0.0, 0.0, 1.0], dtype=np.float32), float(angle_rad))
+        elif canonical_bone in ["right_arm", "right_shoulder"]:
+            return quat_from_axis_angle(np.array([0.0, 0.0, 1.0], dtype=np.float32), float(-angle_rad))
+
+        return quat_identity()