Simulation backend for visualizing K-Infer models in real-time.
kinfer-sim is a Python package that provides a simulation environment for running and visualizing exported K-Infer models. It enables developers to test and validate their trained policies in simulation before deploying them to physical K-Scale robots like K-Bot.
This tool is part of the K-Scale Labs ecosystem, which provides an integrated open-source stack for humanoid robotics—from hardware design to machine learning models.
- Real-time visualization of K-Infer model policies
- Automatic MJCF downloading from the K-Scale API
- Command-line interface for quick testing
- Sim-to-real validation before hardware deployment
- Support for various robot models including K-Bot
Install via pip:
pip install kinfer-simRun an exported K-Infer model with a single command:
kinfer-sim examples/kbot_walking.kinfer kbot-headless --use-keyboardThis will:
- Load the specified
.kinfermodel file - Automatically download the robot's MJCF description from the K-Scale API
- Launch the simulation viewer
kinfer-sim <kinfer-path> <mujoco-model-name> [OPTIONS]Positional Arguments:
kinfer-path: Path to your exported K-Infer model (.kinferfile)mujoco-model-name: Name of the robot model (e.g.,kbot,zbot)
MuJoCo Settings:
--mujoco-scene <str>: MuJoCo scene to use (default:smooth)--no-cache: Don't use cached metadata--debug: Enable debug logging--local-model-dir <path>: Path to local robot directory containingmetadata.jsonand*.mjcf/*.xml(bypasses K-Scale API)
Physics Settings:
--dt <float>: Simulation timestep (default:0.0001)--pd-update-frequency <float>: PD update frequency for actuators in Hz (default:1000.0)--no-gravity: Disable gravity--start-height <float>: Initial height of the robot in meters (default:1.1)--initial-quat <w,x,y,z>: Initial quaternion as comma-separated values (e.g.,1.0,0.0,0.0,0.0)--suspend: Suspend robot base in place to prevent falling--quat-name <str>: Name of the quaternion sensor (default:imu_site_quat)--acc-name <str>: Name of the accelerometer sensor (default:imu_acc)--gyro-name <str>: Name of the gyroscope sensor (default:imu_gyro)
Rendering Settings:
--no-render: Disable rendering--render-frequency <float>: Render frequency in Hz (default:1.0)--frame-width <int>: Frame width in pixels (default:640)--frame-height <int>: Frame height in pixels (default:480)--camera <str>: Camera to use for rendering--save-path <path>: Path to save logs and videos (default:logs)--save-video: Save video of the simulation--save-logs: Save simulation logs--free-camera: Enable free camera control
Model Settings:
--use-keyboard: Use keyboard to control the robot with a 16 dim command defined inkinfer_sim/keyboard.py
Randomization Settings (for domain randomization testing):
--command-delay-min <float>: Minimum command delay in seconds--command-delay-max <float>: Maximum command delay in seconds--drop-rate <float>: Drop actions with this probability (default:0.0)--joint-pos-delta-noise <float>: Joint position delta noise in degrees (default:0.0)--joint-pos-noise <float>: Joint position noise in degrees (default:0.0)--joint-vel-noise <float>: Joint velocity noise in degrees/second (default:0.0)--joint-zero-noise <float>: Joint zero noise in degrees (default:0.0)--accelerometer-noise <float>: Accelerometer noise in m/s² (default:0.0)--gyroscope-noise <float>: Gyroscope noise in rad/s (default:0.0)--projected-gravity-noise <float>: Projected gravity noise in m/s² (default:0.0)
Enable 16 dimensional keyboard control:
kinfer-sim <kinfer-path> kbot-headless --use-keyboard --command-type unifiedTest with domain randomization:
kinfer-sim <kinfer-path> kbot-headless \
--drop-rate 0.1 \
--joint-pos-noise 0.5 \
--gyroscope-noise 0.01Use local robot model:
kinfer-sim <kinfer-path> kbot-headless --local-model-dir <path to local model>Suspend robot for testing:
kinfer-sim <kinfer-path> kbot-headless --suspendK-Infer is K-Scale Labs' model export and inference tool. It converts trained reinforcement learning policies into an optimized format (.kinfer files) that can be:
- Visualized in simulation using
kinfer-sim - Deployed to physical robots using the K-Scale runtime
- Shared and evaluated in the K-Scale benchmarks
kinfer-sim works seamlessly with other K-Scale tools:
- K-Sim / IsaacLab / IsaacGym: GPU-accelerated training environments for learning policies
- K-Infer: Model export and inference tool
- kinfer-sim: This package - for visualization and validation (you are here!)
- Firmware: For deploying policies to physical hardware
- Train a policy using K-Sim, IsaacLab, or IsaacGym
- Export the policy using K-Infer to create a
.kinferfile - Validate the policy using
kinfer-sim(this tool) - Deploy to physical robot using firmware
For more information about the K-Scale ecosystem:
- Main Documentation: https://docs.kscale.dev
- Simulation Guide: https://docs.kscale.dev/robots/k-bot/simulation
- K-Scale Labs: https://kscale.dev
- Discord: Join our Discord community for real-time help
- Issues: Report bugs or request features on GitHub Issues
We welcome contributions! K-Scale Labs is building the world's most accessible platform for embodied intelligence, and we believe in open-source collaboration.
To contribute:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
Check out our GitHub organization for more projects to contribute to.
This project is licensed under the MIT License - see the LICENSE file for details.
If you use this software in your research, please cite:
@software{kinfer_sim,
title = {kinfer-sim: Simulation backend for K-Infer models},
author = {K-Scale Labs},
year = {2025},
url = {https://github.com/kscalelabs/kinfer-sim}
}Built with ❤️ by K-Scale Labs - Making robots accessible to everyone.