Quick Start

What is Motionscope?

Motionscope is PARC’s interactive motion and terrain editor built on top of Polyscope. It provides a powerful GUI for:

Visualizing character animations with terrain
Editing motion sequences and contact labels
Generating motions using trained MDM models
Planning paths and optimizing kinematic motions
Real-time kinematic control (with RTX 4090)

Motionscope is a standalone tool that can be used independently of the full PARC training pipeline. It’s perfect for exploring motion data and understanding character animations.

Quick Start: Launch Motionscope

Let’s get Motionscope running in just a few steps.

Configure Motion to Load

Before launching Motionscope, edit the configuration file to specify which motion to load:

PARC/motionscope/motionscope_config.yaml

load_mdm: False
use_contact_info: True
use_legacy_file_format: False

motions:
  - ["data/motion_terrains/sfu.pkl", "humanoid"]

terrain_mesh_mode: "simple" # [simple, greedy]
load_other_motion_terrains: False
input_folder_dir: "data/terrains/"

mdm_filepaths:
  main: "$DATA_DIR/tests/parc/jan022025/p1_train_gen/checkpoints/model_40000.ckpt"

Make sure the motion file path exists. If you don’t have motion data yet, download it from the PARC HuggingFace dataset.

Run Motionscope

Launch the viewer from the repository root:

python scripts/run_motionscope.py

The Polyscope window should open showing your character animation!

Explore the Interface

Motionscope provides several GUI panels accessible through the sidebar:

Time GUI: Motion playback controls (play/pause, frame stepping, timeline scrubbing)
Motion GUI: Edit motion sequences and transform characters
Contact GUI: Edit contact labels for feet, hands, and body parts
Terrain GUI: Modify terrain height at specific points
MDM GUI: Generate new motions using loaded diffusion models
Path Planning GUI: Create paths using A* on terrain for motion generation
Optimization GUI: Kinematic optimization for motion refinement

Keyboard Shortcuts

Motionscope includes convenient keyboard shortcuts for quick editing:

Key	Action
Space	Play motion from beginning
E	Jump to end of motion
N	Place path node at mouse position
A	Set terrain elevation at mouse position
C	Set contact body constraint point at mouse position
G	Generate motion using loaded MDM model

Motion Playback Controls

The Motion Playback panel (bottom of screen) provides:

Playback Options

Paused checkbox: Pause/resume playback
Looping checkbox: Enable continuous looping
Previous Frame / Next Frame buttons: Step through frames
Motion time slider: Scrub through the timeline

Motion Information

The panel displays:

Total number of frames
FPS (frames per second)
Current frame index
Motion time in seconds

Loading Your Own Motions

Option 1: Edit Config File

Modify PARC/motionscope/motionscope_config.yaml:

motions:
  - ["/path/to/your/motion.pkl", "humanoid"]

Option 2: Use Motion Library

For multiple motions, reference a motion library YAML file:

motion_lib_file: "$DATA_DIR/Data/parkour_dataset_april/initial/motions.yaml"

Motion File Format

PARC motion files (.pkl) contain:

Root position and rotation trajectories
Joint rotation sequences
Body contact labels
FPS and loop mode metadata
Optional terrain heightfields
Optional path planning data

Files are loaded via PARC/anim/motion_lib.py:MotionLib class.

Visualizing Terrain

Motionscope can display terrain associated with motions:

Enable Terrain Viewing

In the config, ensure terrain data is included:

terrain_mesh_mode: "simple"

View Local Heightfield

Open the Visibility panel and check:

“View local hf” - Shows the local heightfield around the character
Adjust “Local Heightfield Visibility” slider for transparency

Edit Terrain Height

Open Terrain GUI and:

Set desired terrain height
Adjust mouse size (editing radius)
Press A key while hovering over terrain to modify elevation

Using Motion Diffusion Models

If you have a trained MDM checkpoint, you can generate new motions interactively:

Load MDM Model

Edit the config to enable MDM loading:

load_mdm: True

mdm_filepaths:
  main: "$DATA_DIR/path/to/model_checkpoint.ckpt"

Configure Generation Parameters

Open the MDM GUI panel to configure:

Number of candidates to generate
DDIM sampling stride
Target direction conditioning
Temperature/noise settings

Generate Motion

Press G key to generate a new motion at the current terrain location and target direction.

Real-time generation requires RTX 4090. RTX 3090 will be slower than real-time but still functional.

Saving Edited Motions

After editing a motion, you can save it:

Open Saving Panel

Expand the Saving tree in the main GUI panel.

Configure Save Options

Choose what to include:

Save path with motion: Include path planning data
Save motion as loop: Set loop mode to WRAP
Save terrain with motion: Include terrain heightfield

Save Motion File

Click Save Current Motion button. The motion will be saved to:

output/_motions/new_motion.pkl

The file includes:

Root position/rotation trajectories (PARC/anim/motion_lib.py:79-81)
Joint rotations (PARC/anim/motion_lib.py:82)
Contact labels (PARC/anim/motion_lib.py:83)
FPS and loop mode metadata (PARC/anim/motion_lib.py:84-85)
Optional terrain data (scripts/run_motionscope.py:351-357)

Advanced Features

Path Planning GUI

Create navigation paths on terrain for autoregressive motion generation:

Open Path Planning GUI
Press N to place path nodes at mouse positions
Configure A* planning parameters
Generate motion sequence along the path

Path planning uses PARC/motion_synthesis/procgen/astar.py with custom terrain graph traversal.

Kinematic Optimization

Refine motions using inverse kinematics:

Open Optimization GUI
Set body constraints for feet, hands, or other body parts
Run optimization to adjust motion while satisfying constraints
Useful for fixing foot sliding or maintaining contact points

Contact Editing

Edit contact labels frame-by-frame:

# Available contact bodies:
- Left Foot
- Right Foot  
- Left Hand
- Right Hand
- Torso
- Head

Viewing Options

Customize visualization in the Visibility panel:

Motion sequence: Show/hide skeleton sequence overlay
Shadow: Character projection on ground plane
Body points: Display joint positions
Target direction: Arrow showing movement direction
Origin axes: XYZ axes at world origin

Troubleshooting

Motionscope Won’t Launch

Issue: Script fails to start or shows OpenGL errors Solution:

Ensure you have OpenGL support (required by Polyscope)
On headless servers, use X11 forwarding: ssh -X user@host
Check that Python can import polyscope: python -c "import polyscope"

Motion File Not Found

Issue: FileNotFoundError when launching Solution:

Verify the path in motionscope_config.yaml exists
Use absolute paths or paths relative to repo root
Download sample data from HuggingFace
For $DATA_DIR paths, ensure user_config.yaml is configured

MDM Model Won’t Load

Issue: Errors loading checkpoint file Solution:

Ensure load_mdm: True in config
Verify checkpoint path is correct and file exists
Check PyTorch version compatibility (requires 2.2.0)
Ensure CUDA is available if model was trained on GPU

Isaac Gym Import Errors on Non-Linux

Issue: Import errors for isaacgym on Windows/macOS Solution: This is expected - the script detects the platform:

scripts/run_motionscope.py:12-19

if platform.system() == "Linux":
    print("Running on Linux, importing isaac gym")
    g_running_on_linux = True
    import isaacgym.gymapi as gymapi
else:
    g_running_on_linux = False

Isaac Gym features are disabled on non-Linux platforms. Core Motionscope functionality still works.

Next Steps

Now that you’re familiar with Motionscope, explore:

PARC Training Loop

Learn the 4-stage iterative training process

Motion Generation

Train your own motion diffusion models

Physics Tracking

Train tracking controllers in Isaac Gym

API Reference

Explore PARC’s Python API

Get Started

Core Concepts

Guides

Resources

Quick Start

What is Motionscope?

Quick Start: Launch Motionscope

Keyboard Shortcuts

Motion Playback Controls

Loading Your Own Motions

Option 1: Edit Config File

Option 2: Use Motion Library

Motion File Format

Visualizing Terrain

Using Motion Diffusion Models

Saving Edited Motions

Advanced Features

Path Planning GUI

Kinematic Optimization

Contact Editing

Viewing Options

Troubleshooting

Motionscope Won’t Launch

Motion File Not Found

MDM Model Won’t Load

Isaac Gym Import Errors on Non-Linux

Next Steps

PARC Training Loop

Motion Generation

Physics Tracking

API Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Resources

​What is Motionscope?

​Quick Start: Launch Motionscope

​Keyboard Shortcuts

​Motion Playback Controls

​Loading Your Own Motions

​Option 1: Edit Config File

​Option 2: Use Motion Library

​Motion File Format

​Visualizing Terrain

​Using Motion Diffusion Models

​Saving Edited Motions

​Advanced Features

​Path Planning GUI

​Kinematic Optimization

​Contact Editing

​Viewing Options

​Troubleshooting

​Motionscope Won’t Launch

​Motion File Not Found

​MDM Model Won’t Load

​Isaac Gym Import Errors on Non-Linux

​Next Steps

PARC Training Loop

Motion Generation

Physics Tracking

API Reference

Build docs developers (and LLMs) love

What is Motionscope?

Quick Start: Launch Motionscope

Keyboard Shortcuts

Motion Playback Controls

Loading Your Own Motions

Option 1: Edit Config File

Option 2: Use Motion Library

Motion File Format

Visualizing Terrain

Using Motion Diffusion Models

Saving Edited Motions

Advanced Features

Path Planning GUI

Kinematic Optimization

Contact Editing

Viewing Options

Troubleshooting

Motionscope Won’t Launch

Motion File Not Found

MDM Model Won’t Load

Isaac Gym Import Errors on Non-Linux

Next Steps