A library for visualizing robotics motion data from MuJoCo XML models
npm install smooviz-roboticsA powerful library for visualizing robotics motion data from MuJoCo XML models. Works with both React applications and vanilla JavaScript.
- Parse MuJoCo XML robot models
- Build 3D robot visualizations using Three.js
- Animate robots with motion data
- Multiple distribution formats:
- ESM/CJS modules for bundlers (Webpack, Vite, etc.)
- UMD bundle for vanilla HTML/JavaScript
- TypeScript type definitions included
- Framework agnostic core with optional React components
``bash`
npm install smooviz-robotics react react-dom three
or with yarn:
`bash`
yarn add smooviz-robotics react react-dom three
Download the UMD bundle or use a CDN:
`html`
The simplest way to get started - just render the component and use the built-in configuration dialog:
`tsx
import { RobotVisualizer } from 'smooviz-robotics';
function App() {
return (
Or skip the dialog and go straight to visualization:
tsx
import { RobotVisualizer } from 'smooviz-robotics';function App() {
return (
dataUrl="/unitree_g1/example.json"
/>
);
}
`$3
tsx
import { useEffect, useRef } from 'react';
import * as THREE from 'three';
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';
import {
parseMuJoCoXML,
buildRobotFromModel,
applyJointAngles
} from 'smooviz-robotics/core';function CustomRobotViewer() {
const containerRef = useRef(null);
useEffect(() => {
if (!containerRef.current) return;
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
containerRef.current.appendChild(renderer.domElement);
// Set up lights and camera
scene.add(new THREE.AmbientLight(0xffffff, 0.5));
const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8);
directionalLight.position.set(5, 10, 7);
scene.add(directionalLight);
camera.position.set(2, 2, 2);
const controls = new OrbitControls(camera, renderer.domElement);
// Load and visualize robot
async function loadRobot() {
const model = await parseMuJoCoXML('/path/to/robot.xml');
const robot = await buildRobotFromModel(model, '/path/to/meshes');
scene.add(robot.robot);
// Load motion data and animate
const response = await fetch('/path/to/motion.json');
const motionData = await response.json();
let frame = 0;
setInterval(() => {
applyJointAngles(robot, motionData.dof_pos[frame]);
frame = (frame + 1) % motionData.dof_pos.length;
}, 1000 / motionData.fps);
}
loadRobot();
function animate() {
requestAnimationFrame(animate);
controls.update();
renderer.render(scene, camera);
}
animate();
return () => {
renderer.dispose();
containerRef.current?.removeChild(renderer.domElement);
};
}, []);
return
;
}
`$3
html
Robot Viewer
`API Reference
$3
####
Parses a MuJoCo XML file and returns a structured model.
Parameters:
-
- URL or path to the MuJoCo XML fileReturns:
- Promise that resolves to a
MuJoCoModel containing the robot structure####
buildRobotFromModel(model: MuJoCoModel, meshBaseUrl: string): PromiseBuilds a Three.js scene graph from a parsed MuJoCo model.
Parameters:
-
- The parsed MuJoCo model
- meshBaseUrl - Base URL for loading mesh files (STL)Returns:
- Promise that resolves to a
RobotStructure containing the Three.js robot and joint mappings####
applyJointAngles(robotStructure: RobotStructure, jointAngles: number[]): voidApplies joint angles to the robot for animation.
Parameters:
-
- The robot structure from buildRobotFromModel
- - Array of joint angles in radians#### Utility Functions
-
getAllJoints(body: MuJoCoBody): MuJoCoJoint[] - Get all joints in order
- findBodyByName(body: MuJoCoBody, name: string): MuJoCoBody | null - Find a specific body
- buildBodyMap(rootBody: MuJoCoBody): Map - Create name-to-body lookup$3
####
A complete React component for visualizing robot motion.
Props:
-
(optional) - Robot model to load
- dataUrl?: string (optional) - URL to the motion data JSON fileConfiguration Dialog:
When both props are omitted, the component displays a configuration dialog allowing users to:
- Select a robot model from available options
- Specify a motion data file path
Relative paths in
dataUrl are resolved from the model directory. For example, if modelName="unitree_g1" and dataUrl="example.json", the component will load /unitree_g1/example.json.Examples:
`tsx
// Show configuration dialog
// Direct visualization with specific model and data
dataUrl="/unitree_g1/example.json"
/>
// Use relative path for data (resolves to /unitree_g1/example.json)
dataUrl="example.json"
/>
`$3
The library exports comprehensive TypeScript types:
typescript
import type {
MuJoCoModel,
MuJoCoBody,
MuJoCoJoint,
MuJoCoGeom,
MuJoCoScene,
RobotStructure,
JointInfo
} from 'smooviz-robotics';
`Motion Data Format
The library expects motion data in the following JSON format:
json
{
"dof_pos": [[/ joint angles for frame 0 /], [/ frame 1 /], ...],
"root_pos": [[x, y, z], ...],
"root_ori": [[x, y, z, w], ...],
"fps": 30
}
`-
- 2D array of joint angles (radians) for each frame
- root_pos - Root position [x, y, z] for each frame
- root_ori - Root orientation quaternion [x, y, z, w] for each frame
- fps - Playback frame rateMuJoCo XML Format
The library supports standard MuJoCo XML format with:
-
- Robot hierarchy
- - Mesh and material definitions
- - Modular file composition
- Scene settings (lights, ground, camera)Examples and Assets
$3
See the
examples/ directory for complete working examples:
- react-example.tsx - React usage with custom implementation
- vanilla-js-example.html - Vanilla JavaScript usage$3
The library includes example robot models and motion data in the
public/ directory:
- public/unitree_g1/ - Unitree G1 humanoid robot model
- scene.xml - MuJoCo scene configuration
- custom.xml - Robot model definition
- example.json - Example dancing motion data
- meshes/ - STL mesh files for robot parts
- config.yaml` - Robot configurationThese assets are included when you install the package and can be used for testing and development.
Apache-2.0
Contributions welcome! Please open an issue or submit a pull request.