Instructions to use ttktjmt/mjswan with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- MJLab
How to use ttktjmt/mjswan with MJLab:
# No code snippets available yet for this library. # To use this model, check the repository files and the library's documentation. # Want to help? PRs adding snippets are welcome at: # https://github.com/huggingface/huggingface.js
- Notebooks
- Google Colab
- Kaggle
mjswan demo assets
What the mjswan demo loads. These files live here rather than in the repository, so a clone stays small and a build fetches what it needs.
The scenes mjlab supplies as tasks β G1, Go1, Yam, cartpole β are deliberately not
under scenes/: add_scene_mjlab assembles those from the task itself. What is here is
the one scene mjlab has no task for, the trained policies, which no package ships,
and the skins the Showcase draws over its robots.
Usage
import re
import mjswan
from mjswan.source import hf
REPO = "ttktjmt/mjswan"
builder = mjswan.Builder()
project = builder.add_project(name="Showcase")
scene = project.add_scene_hf(REPO, "scenes/unitree_g1/scene.xml", control_dt=0.02)
scene.add_policy_hf(
REPO, filename=["policies/locomotion.onnx", "policies/balance.onnx"]
)
# Several splats can share one scene; the viewer shows a selector to switch between
# them, and only the selected one is fetched.
scene.add_splat_hf(REPO, "splats/street.spz", name="Street",
scale=3.275, z_offset=0.708, yaw=40)
scene.add_splat_hf(REPO, "splats/cafe.spz", name="Cafe",
scale=3.275, z_offset=0.708)
# An mjlab task's checkpoints, ordered by training step. `list_repo_onnx` sorts as
# strings, which would put `model_1000` before `model_500`.
files = hf.list_repo_onnx(REPO)
prefix = "checkpoints/mjlab-velocity-flat-unitree-g1/"
names = sorted(
(n for n in files if n.startswith(prefix)),
key=lambda n: int(re.search(r"_(\d+)\.onnx$", n).group(1)),
)
builder.build().launch()
Needs pip install mjswan[hf]. Nothing here requires mjlab or torch to load β those
are needed only to build a scene from an mjlab task.
Contents
| Path | What it is |
|---|---|
scenes/unitree_g1/ |
The 29-DoF Unitree G1, as MJCF plus the meshes it resolves. The two policies under policies/ were trained against this XML |
policies/*.onnx |
Locomotion and standing balance for the G1. The matching .json is a sidecar carrying PD gains and the rest of the policy config |
splats/*.spz |
Gaussian Splat captures used as backgrounds. street and cafe go on the same scene, switchable in the viewer |
checkpoints/<task-id>/model_<step>.onnx |
Training checkpoints for an mjlab task. <task-id> is the mjlab task name lowercased; <step> is the training step |
motions/*.npz |
Reference motions for the tracking task |
skins/<author>/ |
Characters drawn over a robot: VRM avatars and rigged glTF animals. See Skins |
Every ONNX under checkpoints/ carries mjlab's metadata_props except the two cartpole
tasks, whose environment has no robot entity and no joint_pos action term for mjlab's
exporter to describe. Where the metadata is present, add_policy_hf reads the joint names
and the rest pose from the file instead of asking for them again β and only when your
scene's own model presents the same joints in actuator order, since pairing lists that
disagree would misdrive every actuator with nothing at playback to say so.
Licensing
This repository mixes licenses.
policies/,checkpoints/,motions/,splats/β Apache-2.0, mjswan Developers.skins/: each file under its own terms; see Skins.scenes/unitree_g1/β see theLICENSEbeside the model. The G1 is Unitree Robotics' and comes from mujoco_menagerie.
A LICENSE under scenes/ travels with the model: mjswan detects it when the scene is
added and copies it into the build output, so a deployed app carries its attributions.
Skins
A skin is a rigged character mjswan draws over a robot and poses from its bodies every
frame (SceneHandle.add_skin). The demo's examples/demo/main.py fits each one here to
WBC-Mjlab's G1 (Humanoid skins) or the Go1 (Quadruped skins). Every file is unmodified
from where it came from, except pug.glb, which make_pug.py beside it made, and
AvatarSample_A.vrm, whose PNG textures shrink_vrm.py beside it re-encoded losslessly
(the same pixels; the meta and the thumbnail untouched) to fit Cloudflare Pages' 25 MiB
per file.
| Path | From | Author | Terms |
|---|---|---|---|
skins/pixiv/VRM1_Constraint_Twist_Sample.vrm |
vrm-c/vrm-specification | pixiv Inc. | VRM Public License 1.0, in the file's meta |
skins/pixiv/AvatarSample_A.vrm |
VRoid Hub | pixiv (VRoid) | Not CC0: pixiv's AvatarSample terms, in the file's meta and pixiv's help |
skins/pixiv/AvatarSample_B.vrm |
pixiv/ChatVRM, pixiv's own copy | pixiv (VRoid Project) | As AvatarSample_A |
skins/pixiv/AvatarSample_C.vrm |
VRoid Hub | pixiv (VRoid) | As AvatarSample_A |
skins/100avatars/100Avatars_001_Crimsom.vrm, 100Avatars_024_CoolBanana.vrm |
PolygonalMind/100Avatars | Polygonal Mind | CC0 1.0, in each file's meta and the project's release notes; LICENSE.md beside them |
skins/quaternius/pug.glb |
Quaternius's Farm Animals, through make_pug.py |
Quaternius | CC0 1.0; LICENSE.md beside it |
skins/quaternius/shiba_inu.glb, fox.glb |
Poly Pizza, Poly Pizza | Quaternius | CC0 1.0; LICENSE.md beside it |
A VRM's license is its meta, which mjswan bundles byte for byte; a .glb takes its
license and notice from its SkinConfig. AvatarSample_A to C may be used and
redistributed by anyone, for profit or not, without credit, as pixiv distributes them:
never relabel them as CC0, sell them or put them behind a paid feature, offer an editor
for their looks, or imply that pixiv or VRoid endorse your work.