Principle:Haosulab ManiSkill Asset Download Loading
| Knowledge Sources | |
|---|---|
| Domains | Robotics, Simulation, Data_Management |
| Last Updated | 2026-02-15 08:00 GMT |
Overview
Asset management is the system for downloading, registering, versioning, and loading the 3D models, robot descriptions, and scene datasets that populate a simulation, ensuring that simulation environments can be reproduced on any machine with a single command.
Description
Robotics simulation depends on a large collection of assets: robot URDF/MJCF model files with associated meshes and textures, object models from datasets like YCB and PartNet-Mobility, scene datasets like ReplicaCAD and AI2THOR, and auxiliary data like demonstration trajectories. These assets are too large to bundle with the simulation library itself and must be downloaded on demand.
The Asset Management principle provides a centralized system for this. Each asset source is registered with a unique identifier, a download URL (typically a HuggingFace repository), a target directory, and an optional checksum. A CLI tool and programmatic API allow users to download individual assets or entire asset groups (e.g., "all robot models" or "all tabletop task objects"). The system tracks which assets have been downloaded and can detect when assets need updating.
Beyond downloading, the principle also covers loading: URDF and MJCF loaders parse robot and object description files into the simulation engine's internal representation. The URDF loader handles the standard Unified Robot Description Format used by ROS and most robot manufacturers. The MJCF loader handles MuJoCo's XML format, which is used by many benchmark environments and the RoboCasa fixture system. Both loaders support parallelized loading for GPU simulation, where the same model must be instantiated across many environments simultaneously.
Specialized builders handle procedurally generated assets: ground planes with configurable textures and dimensions, ROBEL-style valves constructed from geometric primitives, and other parametric objects that do not come from external files.
Usage
This principle applies whenever:
- A simulation environment requires 3D models that are not bundled with the library and must be downloaded from an external source.
- Robot models in URDF or MJCF format must be parsed and instantiated in the physics engine.
- Asset availability must be verified before environment creation, with automatic download prompts when assets are missing.
- The same model must be loaded into thousands of parallel environments efficiently.
- Procedural assets (ground planes, parametric objects) must be generated at runtime.
Theoretical Basis
1. Asset Registry: Each asset source is a data record containing:
- A unique string identifier (e.g., "ycb", "partnet_mobility", "replicacad").
- A source URL pointing to a versioned repository (typically HuggingFace).
- A local target directory path, defaulting to a user-configurable data root.
- An output directory name for the extracted files.
- Optional metadata such as checksums and version tags.
Assets can be grouped into logical collections (e.g., "all assets needed for tabletop tasks") so that users can download everything needed for a set of tasks with a single command.
2. Download Protocol: The download system checks whether the target directory already exists. If not, it downloads the asset archive from the registered URL, extracts it to the target directory, and optionally verifies integrity. The CLI interface provides progress feedback and supports selective downloading of individual assets.
3. URDF Loading: The Unified Robot Description Format (URDF) is an XML format that describes a robot's kinematic tree (links connected by joints), dynamic properties (masses, inertias, friction), collision geometry, and visual meshes. The URDF loader parses this file and creates the corresponding articulation in the physics engine. For GPU simulation, the loader supports building multiple instances of the same articulation in parallel, sharing mesh data across instances to minimize GPU memory usage.
4. MJCF Loading: The MuJoCo XML Format (MJCF) is a richer description format that supports composite bodies, tendons, actuators, sensors, and scene-level elements. The MJCF loader handles the subset of MJCF features relevant to rigid-body simulation: body hierarchies, joint definitions, geom shapes, and material properties. It includes an internal loader for low-level parsing and a public-facing wrapper that adds parallelization support.
5. Procedural Asset Generation: Some assets are generated algorithmically rather than loaded from files. Ground planes are created from simple geometric primitives with configurable dimensions and textures. ROBEL valves are constructed by composing cylinders and capsules into a valve shape with configurable tri-petal geometry. These builders follow the same interface as file-based loaders but produce geometry programmatically.
Related Pages
- Implementation:Haosulab_ManiSkill_AssetData -- Asset source registration and data group definitions.
- Implementation:Haosulab_ManiSkill_DownloadAsset -- CLI tool and library function for downloading assets.
- Implementation:Haosulab_ManiSkill_MJCFLoader -- Public MJCF loader with parallelization support.
- Implementation:Haosulab_ManiSkill_URDFLoader -- Public URDF loader with parallelization support.
- Implementation:Haosulab_ManiSkill_MJCFLoaderInternal -- Internal MJCF parsing and body tree construction.
- Implementation:Haosulab_ManiSkill_GroundBuilder -- Procedural ground plane generation.
- Implementation:Haosulab_ManiSkill_ROBELValveBuilder -- Procedural ROBEL valve articulation construction.