A robot's pose in 3D from its URDF and live joint values (ROS sensor_msgs/JointState), for monitoring: neutral greys from the theme, a ground grid and axes named in words; highlighted joints in a status colour with a callout naming them; orbit, pan and zoom by pointer and keys; loading, error with the failing file, empty, stale and no-WebGL states in words. The kit's one three.js item.
Robot model default
npx shadcn add @syncrobotic/robot-model Also installs: three@^0.187.0, urdf-loader@^0.13.1, lucide-react, @syncrobotic/cn, @syncrobotic/button, @syncrobotic/button-group, @syncrobotic/spinner, @syncrobotic/skeleton
Overview
When to use
- An arm's pose on its robot page, from /joint_states.
- Showing which joint is near its limit, or the pose a robot stopped in, beside the alarm that says so.
- Checking a robot's description: that the URDF loads and its joints turn the right way.
Use something else
- Where robots are on a site: Robot map.
- What the robot sees: Camera feed.
- A few joint values to read at a glance:
data-piecesor a table, which need no 3D.
More examples
States and real uses. Each example is also a Storybook story and a visual regression test.
Robot model animated
Robot model highlighted joint
Robot model loading
Robot model error
Robot model stale
Robot model text fallback
Robot model empty
Usage rules
- For watching a robot's pose: an arm at work, a joint near its limit, the pose a fault stopped it in. It shows the robot and never moves it; jogging and teleoperation are other controls.
- Pass
jointsas ROS sends them (radians, metres for prismatic joints);jointStateToRecordturns asensor_msgs/into the record. A value past a limit is drawn where it is, not clamped: the view shows what the robot reports.JointState - Highlight only what needs someone (a joint near its limit, a link in fault), a handful at most. The link is drawn in the warning colour (
highlightStatus="danger"for a fault) and a callout names the joint with its value and limits, so it never rests on colour alone. - Pass
staleAfterMswhenever the joints come from a live topic (1 s for /joint_states at 10 Hz or more), andupdatedAtfrom the message's stamp: the last pose stays, dimmed, with when it arrived. WithoutupdatedAtonly a change of value counts as an update, so a robot holding still goes stale. - Serve meshes from your own origin:
packagesmaps eachpackage://name to a URL,meshBaseUrlis the folder for the rest. STL and COLLADA load; a file that fails is named in the error. - One view per screen. Each view holds a WebGL context and browsers allow only a few; for a fleet, list the robots and open one view for the robot chosen.
- Load it lazily (
next/ordynamic React.lazy): three.js is large, and only the screens that show a robot model should download it.
Changelog
- 0.24.22026-11-21Mimic joints follow the joint they mimic with limits ignored on every joint, and the driving joint's value wins over a mimic's own whatever the order; a mimic joint can be highlighted by name (
RobotModelInfo.mimics). Planar and floating joints take [x, y, θ] and [x, y, z, roll, pitch, yaw] and are written per component in mm and ° (newposeValuelabel,jointValueWords,jointValueOf); one number no longer leaves their other components undefined. - 0.24.12026-11-21Stale now follows the joint values (or
updatedAt), not thejointsobject: an inline record no longer keeps the view fresh, or flips it in and out of Stale and announces it on every render; withoutupdatedAta robot holding still goes stale. A view rebuilt after a lost context no longer stays on “Restoring the 3D view…”, and a context not back within 5 s shows an error with Load again (new labelcontextFailed). An empty URDF file is an error instead of an endless load; meshes that arrive after the view is gone are freed; mesh paths with a query string load; a theme set on any ancestor is followed; a theme colour that does not parse no longer takes the previous one. - 0.24.02026-11-21First release.