A CLI for processing composite Wavefront OBJ files into a MuJoCo-conducive format
Project description
obj2mjcf
obj2mjcf
is a CLI for processing composite Wavefront OBJ files into a MuJoCo-conducive format. It automatically:
- Splits an OBJ file into sub-meshes that are grouped by the materials referenced in the OBJ's MTL file
- Creates a collision mesh by performing a convex decomposition of the OBJ with V-HACD
- Generates an MJCF XML file that is pre-filled with materials, meshes and geom elements referencing these OBJ files
The generated meshes can then be used as a drop-in replacement for the original OBJ file. The result is vastly enhanced visuals for your model:
Before | After |
---|---|
Motivation
As of June 2022, MuJoCo does not support composite OBJ files consisting of groups or objects (o
or g
OBJ tags) and only 1 material can be assigned per mesh. This means that you have to manually split your OBJ file into sub-meshes, a process that is tedious and error-prone. This tool is meant to automate this process.
Installation
The recommended way to install this package is via PyPI:
pip install --upgrade obj2mjcf
Extra: V-HACD 4.0
We recommend installing V-HACD v4.0. If available, obj2mjcf
will leverage it to create better collision geometry for your OBJ file.
# For macOS and Linux.
bash install_vhacd.sh
Usage
usage: obj2mjcf [-h] --obj-dir STR [--obj-filter STR] [--save-mtl] [--save-mjcf] [--compile-model] [--verbose] [--vhacd-args.enable]
[--vhacd-args.max-output-convex-hulls INT] [--vhacd-args.voxel-resolution INT] [--vhacd-args.volume-error-percent FLOAT]
[--vhacd-args.max-recursion-depth INT] [--vhacd-args.disable-shrink-wrap] [--vhacd-args.fill-mode {FLOOD,SURFACE,RAYCAST}]
[--vhacd-args.max-hull-vert-count INT] [--vhacd-args.disable-async] [--vhacd-args.min-edge-length INT] [--vhacd-args.split-hull]
[--texture-args.resize-percent FLOAT]
A CLI for processing composite Wavefront OBJ files into a MuJoCo-conducive format.
required arguments:
--obj-dir STR path to a directory containing obj files. All obj files in the directory will be
converted
optional arguments:
-h, --help show this help message and exit
--obj-filter STR only convert obj files matching this regex (default: None)
--save-mtl save the mtl files
--save-mjcf save an example XML (MJCF) file
--compile-model compile the MJCF file to check for errors
--verbose print verbose output
optional vhacd_args arguments:
arguments to pass to V-HACD
--vhacd-args.enable enable convex decomposition using V-HACD
--vhacd-args.max-output-convex-hulls INT
maximum number of output convex hulls (default: 32)
--vhacd-args.voxel-resolution INT
total number of voxels to use (default: 100000)
--vhacd-args.volume-error-percent FLOAT
volume error allowed as a percentage (default: 1.0)
--vhacd-args.max-recursion-depth INT
maximum recursion depth (default: 14)
--vhacd-args.disable-shrink-wrap
do not shrink wrap output to source mesh
--vhacd-args.fill-mode {FLOOD,SURFACE,RAYCAST}
fill mode (default: FLOOD)
--vhacd-args.max-hull-vert-count INT
maximum number of vertices in the output convex hull (default: 64)
--vhacd-args.disable-async
do not run asynchronously
--vhacd-args.min-edge-length INT
minimum size of a voxel edge (default: 2)
--vhacd-args.split-hull
try to find optimal split plane location
optional texture_args arguments:
--texture-args.resize-percent FLOAT
resize the texture to this percentage of the original size (default: 1.0)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for obj2mjcf-0.0.18-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d161290fd1266f3d45a61d4079d0ae795dada793539bcfdf08301d9138f6463e |
|
MD5 | fc47187e8be3be3ca427a88490939b78 |
|
BLAKE2b-256 | 3da19769be7ea9d42f4e96a1c985190589c22184fd4f51c3c9445c9bedc95d86 |